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

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

@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

<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

<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

<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

<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

<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

<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

<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

<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

<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! 🎨