# Card Sort Tooltips Implementation

## Overview
This implementation adds tooltip functionality to card sort studies, allowing researchers to provide context for **Compeer-specific or agriculture/finance-specific terms** that may need clarification for participants.

## Features

### For Researchers (Study Management)
- **Add Tooltips**: Click "+ Add Tooltip" button next to each card in the card management interface
- **Edit Tooltips**: Click "📝 Edit Tooltip" to modify existing tooltips
- **Modal Interface**: Clean modal dialog for entering tooltip text
- **Optional**: Tooltips are completely optional - not all cards need them

### For Participants (Card Sort Session)
- **Visual Indicator**: Cards with tooltips display a small "ℹ" icon
- **Click to Reveal**: Participants click the info icon or card to see the tooltip
- **Non-Intrusive**: Tooltip appears above the card without disrupting the sort workflow
- **Easy to Close**: Click elsewhere to dismiss the tooltip

## Technical Implementation

### Database
- **New Column**: `cards.tooltip` (TEXT, nullable)
- **Migration Script**: `scripts/add_card_tooltips_column.sql`
- **Migration Command**: Run this SQL against your database to add the column

```sql
ALTER TABLE `cards` ADD COLUMN `tooltip` TEXT NULL DEFAULT NULL AFTER `title`;
```

### Files Modified

#### 1. **Backend - API** (`public/api/cards_list.php`)
- Updated to include `tooltip` field in API response if column exists
- Gracefully handles databases without the tooltip column
- Dynamic column detection ensures backward compatibility

#### 2. **Researcher Interface** (`public/studies/cards.php`)
- Added tooltip management buttons for each card
- Implemented modal dialog for editing tooltips
- Backend form handler for saving tooltips via `update_tooltip` action
- Button states indicate whether tooltip exists

#### 3. **Participant Interface** (`public/participant.php`)
- Enhanced `makeCard()` function to detect and display tooltips
- Added tooltip rendering with interactive reveal mechanism
- Tooltip appears above card on demand
- Graceful fallback if tooltip data not present

#### 4. **Styles** (`assets/css/style.css`)
- `.card-with-tooltip` - Container class for cards with tooltip capability
- `.tooltip-icon` - Styled "ℹ" indicator with blue accent color
- `.tooltip-box` - Positioned tooltip box with animation
- `.tooltip-box.show` - State class for visible tooltips
- All styles use existing dark theme variables for consistency

## Usage

### Adding a Tooltip (Researcher)

1. Go to study's card management page (`/public/studies/cards.php?study_id=X`)
2. Find the card you want to add a tooltip to
3. Click "+ Add Tooltip" button
4. Fill in the tooltip text in the modal (e.g., "Compeer - A cooperative organization focused on lending to agriculture")
5. Click "Save Tooltip"
6. Button changes to "📝 Edit Tooltip" indicating it has content

### Viewing a Tooltip (Participant)

1. During card sort, cards with tooltips show a small "ℹ" icon
2. Click on the card or the info icon to reveal the tooltip
3. Tooltip appears above the card
4. Click elsewhere to close the tooltip
5. Continue with card sorting

## Design Considerations

### User Experience
- Non-blocking: Tooltips don't interfere with drag-and-drop functionality
- Visual feedback: Icon makes it clear additional information is available
- Easy access: Single click to reveal
- Responsive: Works on desktop and mobile

### Accessibility
- Semantic HTML structure
- Keyboard-navigable via tab-through cards
- Sufficient color contrast (uses accent color against dark background)
- Information hierarchy clearly established

### Technical
- Backward compatible with existing systems
- Graceful degradation if tooltip column doesn't exist
- Dynamic column detection (no hardcoded schema assumptions)
- Client-side rendering (no additional API calls needed)

## Implementation Details

### How Tooltips Flow Through the System

```
Researcher adds tooltip
    ↓
Form POST to /public/studies/cards.php
    ↓
Action: update_tooltip
    ↓
UPDATE cards SET tooltip = ? WHERE id = ?
    ↓
Data stored in database
    ↓
Participant starts study
    ↓
API: /public/api/cards_list.php returns cards with tooltip field
    ↓
JavaScript renders card with info icon
    ↓
Participant clicks icon/card
    ↓
Tooltip modal appears above card
    ↓
Participant can continue sorting
```

### Database Query Example

```php
// API automatically includes tooltip if column exists
SELECT id, title, tooltip FROM cards WHERE study_id = ? ORDER BY id ASC;
```

### Tooltip Modal Rendering

```javascript
// When tooltip data is present
if (item.tooltip) {
    // Add visual indicator
    // Create hidden tooltip box
    // Attach click handler
    // Add document-level click handler to close
}
```

## Testing

### Researcher Testing
1. Create a new study
2. Add several cards
3. Add tooltips to some (not all) cards
4. Verify button states update correctly
5. Edit existing tooltips

### Participant Testing
1. Preview the study as researcher
2. Look for "ℹ" icons on tooltipped cards
3. Click to reveal tooltips
4. Verify tooltips display correctly above cards
5. Complete card sort and verify no errors

## Troubleshooting

### Tooltips Not Showing
- Verify `tooltip` column was added to database: `DESCRIBE cards;`
- Check if API returns tooltip field: Open browser DevTools, check Network tab
- Ensure cards.php shows Edit Tooltip buttons

### Database Migration Failed
- Check user has ALTER TABLE permissions
- Verify table name is exactly `cards`
- Try adding column with more specific syntax if needed

### Styling Issues
- Check CSS variables are defined (--accent, --panel, --text, etc.)
- Verify style.css is loaded in header
- Check for conflicting CSS rules

## Future Enhancements

Potential improvements for future versions:
- Rich text formatting in tooltips (bold, italics, links)
- Tooltip search/index for research reports
- Translation/localization support for tooltips
- Tooltip usage analytics (how often accessed by participants)
- Tooltip templates for common terms
- Bulk tooltip import from CSV