orion/docs/frontend/shared/ui-components.md

# UI Components Library Implementation Guide

## Overview
This guide covers the implementation of:
1. **Components reference page** - A library showcasing all your UI components
2. **Updated vendor edit page** - Using proper form components
3. **Updated vendor detail page** - Using proper card components
4. **Sidebar navigation** - Adding "Components" menu item

## Files Created

### 1. Components Library Page
**File:** `app/templates/admin/components.html`
- Complete reference for all UI components
- Quick navigation to sections (Forms, Buttons, Cards, etc.)
- Copy-paste ready examples
- Shows validation states, disabled states, helper text, etc.

### 2. Updated Vendor Edit Page
**File:** `app/templates/admin/vendor-edit-updated.html`
- Uses proper form components from your library
- Improved visual hierarchy with card sections
- Better validation state displays (red borders for errors)
- Quick actions section at the top
- Status badges showing current state
- Clean, consistent styling throughout

### 3. Vendor Detail Page  
**File:** `app/templates/admin/vendor-detail.html`
- NEW file (didn't exist before)
- Uses card components to display vendor information
- Status cards showing verification, active status, dates
- Information organized in clear sections
- All vendor data displayed in readable format
- Delete action button

### 4. JavaScript for Detail Page
**File:** `static/admin/js/vendor-detail.js`
- Loads vendor data
- Handles delete action with double confirmation
- Logging for debugging
- Error handling

## Implementation Steps

### Step 1: Add Components Menu to Sidebar

Update your `app/templates/admin/sidebar.html` (or wherever your sidebar is defined):

```html
<!-- Add this menu item after "Settings" or wherever appropriate -->
<li class="relative px-6 py-3">
    <a
        class="inline-flex items-center w-full text-sm font-semibold transition-colors duration-150 hover:text-gray-800 dark:hover:text-gray-200"
        :class="{ 'text-gray-800 dark:text-gray-100': currentPage === 'components' }"
        href="/admin/components"
    >
        <span x-html="$icon('collection', 'w-5 h-5')"></span>
        <span class="ml-4">Components</span>
    </a>
</li>
```

### Step 2: Add Components Page Route

Update your `app/api/v1/admin/pages.py`:

```python
@router.get("/components", response_class=HTMLResponse, include_in_schema=False)
async def admin_components_page(
    request: Request,
    current_user: User = Depends(get_current_admin_from_cookie_or_header),
    db: Session = Depends(get_db)
):
    """
    Render UI components reference page.
    Shows all available UI components for easy reference.
    """
    return templates.TemplateResponse(
        "admin/components.html",
        {
            "request": request,
            "user": current_user,
        }
    )
```

### Step 3: Replace Vendor Edit Template

1. Backup your current: `app/templates/admin/vendor-edit.html`
2. Replace it with: `vendor-edit-updated.html`
3. Keep your existing `vendor-edit.js` (no changes needed)

### Step 4: Add Vendor Detail Template & JavaScript

1. Copy `vendor-detail.html` to `app/templates/admin/vendor-detail.html`
2. Copy `vendor-detail.js` to `static/admin/js/vendor-detail.js`

## Component Usage Guide

### Form Components

#### Basic Input
```html
<label class="block mb-4 text-sm">
    <span class="text-gray-700 dark:text-gray-400">
        Label Text <span class="text-red-600">*</span>
    </span>
    <input
        type="text"
        x-model="formData.fieldName"
        required
        class="block w-full mt-1 text-sm dark:text-gray-300 dark:border-gray-600 dark:bg-gray-700 focus:border-purple-400 focus:outline-none focus:shadow-outline-purple dark:focus:shadow-outline-gray form-input"
    />
</label>
```

#### Input with Validation Error
```html
<label class="block mb-4 text-sm">
    <span class="text-gray-700 dark:text-gray-400">Field Label</span>
    <input
        type="text"
        class="block w-full mt-1 text-sm dark:text-gray-300 dark:bg-gray-700 focus:border-purple-400 focus:outline-none focus:shadow-outline-purple dark:focus:shadow-outline-gray form-input"
        :class="{ 'border-red-600 focus:border-red-400 focus:shadow-outline-red': errors.fieldName }"
    />
    <span x-show="errors.fieldName" class="text-xs text-red-600 dark:text-red-400 mt-1" x-text="errors.fieldName"></span>
</label>
```

#### Disabled Input
```html
<input
    type="text"
    disabled
    value="Read-only value"
    class="block w-full mt-1 text-sm bg-gray-100 border-gray-300 rounded-md dark:bg-gray-700 dark:text-gray-400 dark:border-gray-600 cursor-not-allowed"
/>
```

#### Textarea
```html
<textarea
    x-model="formData.description"
    rows="3"
    class="block w-full mt-1 text-sm dark:text-gray-300 dark:border-gray-600 dark:bg-gray-700 focus:border-purple-400 focus:outline-none focus:shadow-outline-purple dark:focus:shadow-outline-gray form-textarea"
></textarea>
```

### Card Components

#### Stats Card
```html
<div class="flex items-center p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
    <div class="p-3 mr-4 text-orange-500 bg-orange-100 rounded-full dark:text-orange-100 dark:bg-orange-500">
        <span x-html="$icon('user-group', 'w-5 h-5')"></span>
    </div>
    <div>
        <p class="mb-2 text-sm font-medium text-gray-600 dark:text-gray-400">
            Total Users
        </p>
        <p class="text-lg font-semibold text-gray-700 dark:text-gray-200">
            1,234
        </p>
    </div>
</div>
```

#### Info Card
```html
<div class="px-4 py-3 bg-white rounded-lg shadow-md dark:bg-gray-800">
    <h3 class="mb-4 text-lg font-semibold text-gray-700 dark:text-gray-200">
        Card Title
    </h3>
    <div class="space-y-3">
        <div>
            <p class="text-xs font-semibold text-gray-600 dark:text-gray-400 uppercase">Field Label</p>
            <p class="text-sm text-gray-700 dark:text-gray-300">Field Value</p>
        </div>
    </div>
</div>
```

### Button Components

#### Primary Button
```html
<button class="px-4 py-2 text-sm font-medium leading-5 text-white transition-colors duration-150 bg-purple-600 border border-transparent rounded-lg hover:bg-purple-700 focus:outline-none focus:shadow-outline-purple">
    Button Text
</button>
```

#### Button with Icon
```html
<button class="flex items-center px-4 py-2 text-sm font-medium leading-5 text-white transition-colors duration-150 bg-purple-600 border border-transparent rounded-lg hover:bg-purple-700 focus:outline-none">
    <span x-html="$icon('plus', 'w-4 h-4 mr-2')"></span>
    Add Item
</button>
```

#### Secondary Button
```html
<button class="px-4 py-2 text-sm font-medium leading-5 text-gray-700 transition-colors duration-150 bg-white border border-gray-300 rounded-lg hover:border-gray-400 focus:outline-none dark:text-gray-400 dark:border-gray-600 dark:bg-gray-800">
    Cancel
</button>
```

## Features of Updated Pages

### Vendor Edit Page Improvements

1. **Quick Actions Section**
   - Verify/Unverify button
   - Activate/Deactivate button
   - Status badges showing current state
   
2. **Better Form Organization**
   - Clear sections with headers
   - Two-column layout on desktop
   - Helper text for all fields
   - Proper validation states
   
3. **Visual Consistency**
   - Uses standard form components
   - Consistent spacing and sizing
   - Dark mode support
   
4. **User Experience**
   - Disabled states for read-only fields
   - Clear indication of required fields
   - Loading states
   - Error messages inline with fields

### Vendor Detail Page Features

1. **Status Overview**
   - 4 stats cards at top showing key metrics
   - Visual status indicators (colors, icons)
   
2. **Information Organization**
   - Basic info card
   - Contact info card
   - Business details section
   - Owner information section
   - Marketplace URLs (if available)
   
3. **Actions**
   - Edit button (goes to edit page)
   - Delete button (with double confirmation)
   - Back to list button

## Quick Reference: Where to Find Components

When you need a component, visit `/admin/components` and you'll find:

- **Forms Section**: All input types, validation states, helper text
- **Buttons Section**: All button styles and states
- **Cards Section**: Stats cards, info cards
- **Tables Section**: (from your tables.html)
- **Modals Section**: (from your modals.html)
- **Charts Section**: (from your charts.html)

## Testing Checklist

- [ ] `/admin/components` page loads and displays all components
- [ ] Components menu item appears in sidebar
- [ ] `/admin/vendors/{vendor_code}/edit` displays correctly
- [ ] Form validation shows errors in red
- [ ] Quick actions (verify/activate) work
- [ ] `/admin/vendors/{vendor_code}` displays all vendor data
- [ ] Status cards show correct information
- [ ] Edit button navigates to edit page
- [ ] Delete button shows double confirmation
- [ ] All pages work in dark mode
- [ ] All pages are responsive on mobile

## Color Scheme Reference

Your component library uses these color schemes:

- **Primary**: Purple (`bg-purple-600`, `text-purple-600`)
- **Success**: Green (`bg-green-600`, `text-green-600`)
- **Warning**: Orange (`bg-orange-600`, `text-orange-600`)
- **Danger**: Red (`bg-red-600`, `text-red-600`)
- **Info**: Blue (`bg-blue-600`, `text-blue-600`)

## Next Steps

1. Implement the components page route
2. Add menu item to sidebar
3. Replace vendor-edit.html
4. Add vendor-detail.html and .js
5. Test all pages
6. Apply same patterns to other admin pages (users, imports, etc.)

## Tips

- Always reference `/admin/components` when building new pages
- Copy component HTML directly from the components page
- Maintain consistent spacing and styling
- Use Alpine.js x-model for form bindings
- Use your icon system with `x-html="$icon('icon-name', 'w-5 h-5')"`
- Test in both light and dark modes

Enjoy your new component library! 🎨