path: root/WEEK4-PLAN.md

# Week 4 Plan: Forms & Interactions
**Date Started:** 2026-04-16 | **Branch:** `week-4-forms` | **Estimated Duration:** 6–8 hours

---

## 🎯 Week 4 Objectives

### 1. Form Component System
Build a reusable form component library with accessibility and styling.

#### Components to Create:
- **Input Fields** (`.form-input`)
  - Text input, email, password, number
  - States: default, focus, invalid, disabled
  - Placeholder and label styling
  - Error message display
  - Character count support (optional)

- **Textareas** (`.form-textarea`)
  - Resizable or fixed height
  - Auto-expanding variant
  - Character limit indicator
  - Syntax highlighting placeholder (optional)

- **Select Dropdowns** (`.form-select`)
  - Native `<select>` styling
  - Multi-select support
  - Custom styled variant (Alpine.js powered)
  - Accessible keyboard navigation

- **Checkboxes & Radio Buttons** (`.form-checkbox`, `.form-radio`)
  - Custom styled (not browser defaults)
  - Grouped layouts (inline, stacked)
  - Label association (proper `<label for="">`)
  - Accessible keyboard navigation

- **Form Groups** (`.form-group`)
  - Label + input + error message layout
  - Spacing consistency
  - Validation state indicators
  - Help text support

#### Styling Requirements:
- ✅ Dark mode support (all components)
- ✅ Light mode support (all components)
- ✅ Focus indicators (2px ring, visible)
- ✅ Error states (red outline, error message)
- ✅ Disabled states (opacity, cursor)
- ✅ WCAG AA contrast verified
- ✅ Touch targets ≥44px (mobile)
- ✅ Consistent spacing (8px grid)

---

### 2. Form Layouts & Patterns
Implement common form patterns using the component library.

#### Layouts:
- **Single Column**
  - Contact form (name, email, message)
  - Newsletter signup (email, subscribe button)
  - Search form (input, submit)

- **Multi Column**
  - Registration form (2–3 columns on desktop, 1 on mobile)
  - Filter/search form (label + input grids)

- **Inline Forms**
  - Search bar (icon + input + button)
  - Newsletter widget (email + button)

#### Validation Patterns:
- **Client-side** (Alpine.js)
  - Required field checking
  - Email format validation
  - Password strength indicator
  - Conditional field visibility (show/hide based on selection)

- **Server-side Integration**
  - PHP contact form endpoint (`contact.php`)
  - Error message display
  - Success/confirmation messaging
  - CSRF token handling (if applicable)

#### Form States:
- Empty (pristine)
- Focused (active field)
- Filled (has value)
- Invalid (validation error)
- Submitting (loading spinner)
- Submitted (success message)

---

### 3. Modals & Overlays
Build reusable modal components for alerts, confirmations, and content.

#### Modal Variants:
- **Alert Modal** (`.modal-alert`)
  - Single action button (OK, Close)
  - Message display
  - Optional icon

- **Confirmation Modal** (`.modal-confirm`)
  - Two action buttons (Confirm, Cancel)
  - Title + message
  - Danger state (red button for destructive actions)

- **Content Modal** (`.modal-content`)
  - Close button (X)
  - Title + body + footer
  - Large, medium, small sizes
  - Scrollable content

#### Modal Features:
- ✅ Backdrop (semi-transparent overlay)
- ✅ Keyboard handling (Escape to close, Tab trap)
- ✅ Focus management (focus inside modal, restore on close)
- ✅ Animation (fade in/out, slide up)
- ✅ Responsive (full-screen on mobile, centered on desktop)
- ✅ WCAG compliant (role="dialog", aria-labelledby)

#### Alpine.js Integration:
- `x-data="{ open: false }"`
- `@click.outside="open = false"` (close on background click)
- `@keydown.escape="open = false"` (close on Escape)
- Smooth transitions with `x-transition`

---

### 4. Interactive Patterns
Enhance user interactions with feedback and validation.

#### Patterns:
- **Form Submission Feedback**
  - Loading spinner during submission
  - Success toast/notification
  - Error notification with retry
  - Progress indicator (for long forms)

- **Inline Validation**
  - Real-time feedback as user types
  - Email format validation
  - Password strength meter
  - Character count display

- **Loading States**
  - Spinner component (animated SVG or CSS)
  - Button disabled state during submission
  - Loading overlay (for full-page actions)

- **Toast Notifications**
  - Success (green)
  - Error (red)
  - Info (blue)
  - Warning (amber)
  - Auto-dismiss (5 seconds)
  - Manual close button

- **Tooltips**
  - Hover to show/hide
  - Fixed positioning (stays visible)
  - Arrow pointing to target
  - Dark/light mode support

---

## 📊 Implementation Roadmap

| Task | Description | Est. Time | Dependencies |
|------|-------------|-----------|--------------|
| **1. Input Fields** | Text, email, password inputs | 1.5h | Week 3 (CSS vars) |
| **2. Textareas** | Resizable, auto-expand variants | 0.75h | Input fields |
| **3. Selects** | Native + custom styled dropdowns | 1h | Input fields |
| **4. Checkboxes/Radios** | Custom styled with groups | 1h | Input fields |
| **5. Form Groups** | Label + input + error layout | 0.5h | All inputs |
| **6. Form Layouts** | Single/multi-column patterns | 1h | Form groups |
| **7. Validation** | Client-side Alpine.js validation | 1h | Form layouts |
| **8. Modals** | Alert/confirm/content modals | 1.5h | Alpine.js |
| **9. Loading States** | Spinners, disabled buttons | 0.75h | Modals |
| **10. Notifications** | Toast system, tooltips | 1h | Loading states |
| **11. Testing** | Dark/light, mobile, a11y | 1.5h | All components |
| **12. Integration** | Update existing forms/templates | 1h | Testing |

**Total Estimated Time:** 6–8 hours

---

## 🛠 Technical Specifications

### CSS Structure
```
main.css
├── Forms
│   ├── Input fields
│   ├── Textareas
│   ├── Selects
│   ├── Checkboxes/Radios
│   ├── Form groups
│   └── Form layouts
├── Modals
│   ├── Backdrop
│   ├── Dialog containers
│   └── Modal animations
├── States
│   ├── Loading spinners
│   ├── Toast notifications
│   └── Tooltips
└── Utilities
    ├── Z-index management
    ├── Focus management
    └── Responsive overrides
```

### Alpine.js Patterns
```javascript
// Form validation
x-data="{ email: '', error: null }"
@input="validateEmail(email)"

// Modal control
x-data="{ open: false }"
@click.outside="open = false"
@keydown.escape="open = false"

// Loading state
x-data="{ loading: false }"
@click="submitForm()"

// Toast notification
x-data="{ visible: true }"
x-init="setTimeout(() => visible = false, 5000)"
```

### Tailwind CSS Classes
- Form inputs: `.form-input`, `.form-input:focus`, `.form-input:invalid`
- Textareas: `.form-textarea`, `.form-textarea:focus`
- Selects: `.form-select`, `.form-select:focus`
- Checkboxes: `.form-checkbox`, `.form-checkbox:checked`
- Radio buttons: `.form-radio`, `.form-radio:checked`
- Form groups: `.form-group`, `.form-group.error`
- Modals: `.modal`, `.modal-backdrop`, `.modal-content`
- Loading: `.spinner`, `.spinner-sm`, `.spinner-lg`
- Toast: `.toast`, `.toast-success`, `.toast-error`, `.toast-info`, `.toast-warning`
- Tooltips: `.tooltip`, `.tooltip-top`, `.tooltip-bottom`, `.tooltip-left`, `.tooltip-right`

---

## ✅ Testing Strategy

### Functional Testing
- ✅ Form input focus/blur behavior
- ✅ Validation (valid/invalid states)
- ✅ Character count/limits
- ✅ Modal open/close (click button, click outside, press Escape)
- ✅ Toast auto-dismiss
- ✅ Spinner animation
- ✅ Tooltip show/hide

### Responsive Testing
- ✅ Mobile (320px): Single column, full-width inputs
- ✅ Tablet (768px): Multi-column layouts work
- ✅ Desktop (1060px+): Full layout visible

### Accessibility Testing
- ✅ Keyboard navigation (Tab, Shift+Tab, Enter, Space, Escape)
- ✅ Focus indicators (visible on all interactive elements)
- ✅ ARIA labels (form labels, modal title, button text)
- ✅ Focus trap (modal keeps focus inside)
- ✅ Screen reader (semantic HTML, proper roles)

### Dark/Light Mode Testing
- ✅ Form inputs contrast (dark/light)
- ✅ Modal backdrop contrast
- ✅ Toast notifications contrast
- ✅ Spinner color visibility
- ✅ Tooltip background/text contrast

### Cross-browser Testing
- ✅ Chrome (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)

---

## 📝 Deliverables

1. **WEEK4-IMPLEMENTATION.md** — Detailed component documentation
2. **FORM-COMPONENT-GUIDE.md** — Usage examples for all form components
3. **WEEK4-TESTING.md** — Testing checklist and results
4. **CSS Output** — `main.css` with all form/modal/interaction styles
5. **Updated Templates** — Forms integrated into existing pages
6. **HANDOFF.md** — Updated with Week 4 summary

---

## 🚀 Success Criteria

✅ All form components built and styled
✅ Dark/light mode support verified
✅ WCAG AA accessibility verified
✅ Responsive design tested (320px, 768px, 1060px+)
✅ Modal functionality working (open, close, focus trap)
✅ Client-side validation working (real-time feedback)
✅ Toast notifications auto-dismiss
✅ CSS build time < 250ms
✅ No regressions from previous weeks
✅ All components documented with examples

---

## 🔗 Dependencies & Prerequisites

- ✅ Week 3 (Cards & Navigation) completed
- ✅ CSS variables established (colors, spacing)
- ✅ Alpine.js loaded and functional
- ✅ Button/badge component library available
- ✅ Tailwind CSS build pipeline working

---

## ⚙️ Git Workflow

**Branch:** `week-4-forms` (created at session start)
**Base:** `master`
**Merge Strategy:** Review all changes, test thoroughly, merge to master at week end

### Before Starting
```bash
git checkout master
git pull origin master
git checkout -b week-4-forms
npm run watch  # Start CSS watch during development
```

### Before Committing
```bash
npm run build  # Build minified CSS
git add themes/danix-xyz-hacker/assets/css/main.* layouts/partials/...
git commit -m "feat: <component description>"
```

### At Week End
```bash
npm run build  # Final CSS build
git log week-3-cards-nav..week-4-forms  # Review commits
git checkout master
git merge week-4-forms
git push origin master
git branch -d week-4-forms
```

---

## 📚 Reference Materials

- **CSS Variables:** See `COLOR-REFERENCE.md` for all available variables
- **Button Component:** Reference `WEEK2-IMPLEMENTATION.md` for styling patterns
- **Card Component:** Reference `WEEK3-COMPLETION.md` for layout patterns
- **Alpine.js Docs:** https://alpinejs.dev/
- **Tailwind CSS Docs:** https://tailwindcss.com/docs
- **Accessible Forms:** https://www.w3.org/WAI/tutorials/forms/

---

## 🎯 Next Steps (After Week 4)

- **Week 5:** Animations & A11y (CSS keyframes, motion preferences, full audit)
- **Week 6:** Pages & Testing (About, Contact, 404 pages, end-to-end testing)

---

**Status:** Ready to start
**Assigned to:** Danilo M.
**Created:** 2026-04-16