# Content Slides Editor Design

**Date:** 2025-10-27
**Feature:** Hero Slider Content Editor for AMSOIL Dealers
**Goal:** Enable all AMSOIL dealers to create custom hero sliders with their own images and copy while maintaining brand cohesion and extreme usability (4th-grade level).

---

## Overview

The Content Slides Editor is a modal overlay accessible from the dashboard that allows dealers to:
- Create, edit, delete, and reorder 5-10 custom hero slides
- Upload their own images or select from AMSOIL-provided image library
- Customize headline, subheading, and CTA button text
- Apply light text formatting (color from brand palette, bold/italic)
- Preview changes in real-time
- Save and publish slides to their dealer page

The editor prioritizes extreme simplicity and intuitive interaction through:
- Context-aware responsive layout (form width adapts to user focus)
- Horizontal slide thumbnail carousel at bottom
- Collapsible slide list for focused editing
- Live preview of changes as they type
- Visual thumbnail previews throughout

---

## Brand Consistency Constraints

To ensure all dealer sliders feel like part of the AMSOIL brand while allowing customization:

1. **Fixed Button Styling:** CTA buttons always use AMSOIL brand colors and fonts. Dealers only change button text and the link destination.
2. **Image Aspect Ratio Requirement:** All images must fit 16:9 aspect ratio (or similar, TBD based on design). System enforces this with upload validation and crop tool.
3. **Text Positioning Template:** Headline, subheading, and button placement is fixed on all slides. Dealers only change the content, not the layout.

Optional light formatting (color, bold/italic) must stay within a curated brand color palette to maintain consistency.

---

## Feature Requirements

### Slide Content
Each slide contains these customizable elements:
- **Background Image:** Upload or select from library, displayed at 16:9 aspect ratio
- **Headline:** Primary text, up to ~60 characters (with character counter)
- **Subheading:** Secondary text, up to ~120 characters (with character counter)
- **CTA Button:** Button text (up to ~20 characters) + destination URL

### Text Formatting Options
- **Color:** Select from AMSOIL brand color palette (limit to 5-7 on-brand colors)
- **Bold/Italic:** Toggle options to add emphasis
- **No font family or size changes** (styling is fixed for brand consistency)

### Slide Management
- **Slide Count:** Dealers can create 5-10 slides per slider
- **Add Slide:** Button in horizontal slide carousel adds a new blank slide
- **Delete Slide:** Delete button removes current slide (with confirm dialog)
- **Reorder:** Slides can be reordered by dragging thumbnails in the carousel (future enhancement; initial MVP uses Previous/Next or just maintain order)
- **Navigate:** Click any thumbnail to select that slide for editing

### Image Handling
Hybrid approach for maximum dealer flexibility:
- **AMSOIL Image Library:** Tab in image selector showing pre-approved, on-brand AMSOIL images. One-click selection.
- **Custom Upload:** Tab for dealers to upload their own images. System:
  - Validates file type (JPG, PNG)
  - Enforces max file size (e.g., 5MB)
  - Provides a crop tool to fit 16:9 aspect ratio
  - Shows preview of cropped result

### Save & Publish Workflow
- **Manual Save:** Dealers click "Save" button to save changes to that slide
- **Confirm Before Live:** After clicking "Save Changes" in modal footer, show confirmation dialog: "These changes will be published to your dealer page. Continue?"
- **Auto-persistence:** Form data persists while editing (in-memory or session storage) in case of accidental refresh

---

## User Interface Design

### Modal Structure

**Main Content Area (Takes up 80%+ of screen height):**

Two-column responsive layout:
- **Form Section (Left):**
  - Default width: 40%
  - Expands to 50% when user's mouse hovers over form
  - Shrinks back to 40% when mouse leaves form area
  - Smooth CSS transition animation (300-400ms)
  - Contains all input fields and controls

- **Preview Section (Right):**
  - Default width: 60%
  - Shrinks to 50% when user's mouse hovers over form
  - Expands back to 60% when mouse leaves form area
  - Shows live preview of current slide with all formatting applied
  - Visual indicator of hover state (slight opacity change on inactive side)

### Form Section Layout

```
┌─────────────────────────────────────┐
│ Slide 3 of 7                         │
├─────────────────────────────────────┤
│ Image                                │
│ [ Upload Image | AMSOIL Library ]   │
│ [  Image preview/selector  ]         │
├─────────────────────────────────────┤
│ Headline (45/60)                    │
│ [_________ text input _______]      │
│ [Bold] [Italic] [Color picker]      │
├─────────────────────────────────────┤
│ Subheading (80/120)                 │
│ [_________ text input _______]      │
│ [Bold] [Italic] [Color picker]      │
├─────────────────────────────────────┤
│ Button Text (15/20)                 │
│ [_______ text input ______]         │
├─────────────────────────────────────┤
│ Button Link                          │
│ [___ URL input _______________]     │
├─────────────────────────────────────┤
│                 [ Delete Slide ]    │
├─────────────────────────────────────┤
│              [ Save Changes ]        │
└─────────────────────────────────────┘
```

### Horizontal Slide Carousel (Bottom)

```
┌─────────────────────────────────────────────────────────────┐
│                    ▼ (collapse toggle)                       │
├─────────────────────────────────────────────────────────────┤
│ [Thumb1] [Thumb2] [Thumb3:SELECTED] [Thumb4] [Thumb5] [+]  │
│  < scroll left              scroll right >                   │
└─────────────────────────────────────────────────────────────┘
```

**Thumbnail Details:**
- ~100px width × 60px height (16:9 ratio)
- Display background image with headline text overlaid
- Selected thumbnail has a 3px border (AMSOIL brand color)
- Hovering shows subtle scale animation
- "Add Slide" button (+ icon) on right end of carousel
- Horizontal scrollbar if many slides

### Collapse/Expand Behavior

**Expanded State (Default):**
- Chevron ▼ visible above slide carousel
- Slide thumbnails visible and clickable
- Main area takes up ~80% of modal height

**Collapsed State:**
- Chevron ▲ visible above slide carousel (now small)
- Slide carousel hidden (height: 0, overflow: hidden)
- Main form+preview area expands to fill available space
- Smooth animation as carousel collapses/expands

### Modal Header & Footer

**Header:**
- Title: "Edit Slider" or "Customize Your Hero Slider"
- Close button (X) top-right
- Breadcrumb or context (optional): "Dashboard > Edit Slider"

**Footer:**
- Left: "Cancel" button (white/secondary style) → Discards unsaved changes, closes modal
- Right: "Save Changes" button (blue/primary AMSOIL style) → Shows confirmation dialog before publishing

---

## Interactions & State Management

### Editing a Slide
1. Dealer clicks slide thumbnail in carousel
2. Form populates with that slide's current data
3. Dealer edits any field (image, text, etc.)
4. Preview updates in real-time as they type
5. If dealer hovers over form: form expands to 50%, preview shrinks to 50%
6. If dealer hovers over preview: form shrinks to 40%, preview expands to 60%
7. Dealer clicks "Save" button to persist changes to that slide
8. Confirmation dialog appears: "These changes will be published to your dealer page. Continue?"
9. Dealer confirms → changes published, modal can remain open or close

### Adding a Slide
1. Dealer clicks "+ Add Slide" button in carousel
2. New blank slide is created (at end of carousel)
3. New slide is automatically selected
4. Form clears and shows empty fields
5. Dealer fills in content
6. Dealer clicks "Save" to confirm the new slide

### Deleting a Slide
1. Dealer clicks "Delete Slide" button
2. Confirmation dialog: "Are you sure you want to delete this slide?"
3. If confirmed: slide is removed from carousel
4. Adjacent slide (next or previous) is automatically selected
5. If only one slide remains, delete button is disabled

### Image Upload with Crop
1. Dealer clicks "Upload Image" tab
2. File input or drag-drop area for image upload
3. Image loads → Crop tool appears
4. System shows preview of 16:9 crop area
5. Dealer can adjust crop boundaries (visual editor with handles)
6. After crop confirmed, cropped image is applied to slide
7. Preview updates immediately

### Image Library Selection
1. Dealer clicks "AMSOIL Library" tab
2. Grid of pre-approved images displays
3. Dealer clicks an image to select it
4. Image is applied to slide, preview updates immediately

---

## Usability Principles (4th-Grade Level)

1. **One thing at a time:** Form focuses dealer's attention on one slide at a time
2. **Visual feedback:** Preview updates instantly, showing results of edits
3. **Clear labels:** All inputs have descriptive labels, no jargon
4. **Character counters:** Prevent dealers from creating text that breaks layouts
5. **Constraints enforced:** Can't make invalid choices (e.g., aspect ratio enforced, color palette predefined)
6. **Confirmation before destructive actions:** Delete slide, publish changes-both require confirmation
7. **Responsive layout:** Form expands when in focus; preview has priority when scrolling/looking
8. **Collapsed carousel:** Dealers can hide the slide list to focus entirely on content editing

---

## Data Structure

### Slide Model
```typescript
interface Slide {
  id: string;
  order: number;
  image: {
    url: string;
    source: 'upload' | 'library';
    // If source === 'upload': custom image with crop data
    // If source === 'library': reference to library image
  };
  headline: string;
  headlineFormatting: {
    color?: string; // Hex color from brand palette
    bold?: boolean;
    italic?: boolean;
  };
  subheading: string;
  subheadingFormatting: {
    color?: string;
    bold?: boolean;
    italic?: boolean;
  };
  button: {
    text: string;
    url: string;
  };
}

interface SliderContent {
  slides: Slide[];
  publishedAt?: Date;
  updatedAt: Date;
}
```

---

## Implementation Phases

### Phase 1: MVP (Core Editing)
- Modal overlay with form + preview side-by-side
- Add/delete/select slides
- Image upload with crop tool
- Basic text input for headline, subheading, button
- Manual save with confirmation
- Responsive form width (mouse-aware)
- Horizontal slide carousel (non-draggable)

### Phase 2: Enhancements
- AMSOIL image library integration
- Text formatting controls (color, bold, italic)
- Drag-to-reorder slides in carousel
- Collapse/expand slide carousel
- Auto-save drafts
- Undo/redo functionality

### Phase 3: Polish
- Animations and transitions
- Error handling and validation messages
- Loading states for image uploads
- Mobile responsiveness (if needed)
- Analytics tracking for editor usage

---

## Success Criteria

- ✅ A 4th grader can create a complete 5-slide custom hero slider with images and text
- ✅ All dealer sliders maintain AMSOIL brand consistency
- ✅ Live preview updates in real-time
- ✅ Form responsively adapts to user focus with smooth animations
- ✅ No dealer accidentally publishes incomplete content
- ✅ All dealers feel ownership of their customized slider