# UX Improvements - Quick Reference Card

## 🎯 4 Features Shipped

| Feature | File | Lines | Status |
|---------|------|-------|--------|
| Smart Notifications | `useSmartNotifications.ts` | 420 | ✅ Complete |
| Quick Actions FAB | `QuickActionsFAB.vue` | 390 | ✅ Complete |
| Collaborative Cursors | `CollaborativeCursors.vue` | 180 | ✅ Complete |
| Enhanced Empty States | `DashboardPage.web.vue` | +100 | ✅ Complete |

---

## 📚 Import Paths

```typescript
// Smart Notifications
import { useSmartNotifications } from '@/shared/composables/useSmartNotifications'

// Quick Actions FAB
import QuickActionsFAB from '@/shared/components/QuickActionsFAB.vue'
import type { QuickAction } from '@/shared/components/QuickActionsFAB.vue'

// Collaborative Cursors
import CollaborativeCursors from '@/shared/components/CollaborativeCursors.vue'
```

---

## ⚡ Quick Usage

### Smart Notifications
```typescript
const { notify, success, error, warning, info, critical } = useSmartNotifications()

// Simple
success('Opération réussie')

// With actions + grouping
notify({
  message: 'Élément supprimé',
  type: 'warning',
  priority: 'high',
  group: 'delete-actions',
  actions: [
    { label: 'Annuler', icon: 'undo', handler: () => undo() }
  ]
})

// Critical (never auto-dismisses)
critical('Erreur réseau', {
  actions: [
    { label: 'Réessayer', handler: () => retry() }
  ]
})
```

### Quick Actions FAB
```vue
<template>
  <QuickActionsFAB
    :actions="quickActions"
    :badge="notifCount"
    :visible="showFAB"
    position="bottom-right"
    @close="onFABClose"
  />
</template>

<script setup>
const quickActions: QuickAction[] = [
  {
    id: 'add-stage',
    label: 'Ajouter étape',
    subtitle: 'Nouveau lieu',
    icon: 'add_location',
    priority: 3,
    handler: () => openStageDialog()
  },
  {
    id: 'ai-suggest',
    label: 'Suggestions AI',
    icon: 'auto_awesome',
    priority: 2,
    badge: suggestionsCount.value,
    handler: () => openAIPanel()
  },
  {
    id: 'optimize',
    label: 'Optimiser',
    icon: 'route',
    priority: 1,
    loading: isOptimizing.value,
    disabled: !canOptimize.value,
    handler: () => optimize()
  }
]
</script>
```

### Collaborative Cursors
```vue
<template>
  <div class="workspace">
    <!-- Your content -->
    
    <CollaborativeCursors 
      v-if="collabEnabled"
      :presence="activeUsers"
      :inactivity-timeout="10000"
    />
  </div>
</template>

<script setup>
import { useCollaboration } from '@/modules/collab/composables/useCollaboration'

const planId = ref('plan-123')
const collabEnabled = ref(true)

const { presence, ready } = useCollaboration(planId, { enabled: collabEnabled })

const activeUsers = computed(() => ready.value ? presence.value : [])
</script>
```

### Enhanced Empty States
```vue
<template>
  <div v-if="items.length === 0" class="empty-state">
    <div class="empty-state__card">
      <q-icon name="inbox" size="64px" />
      <h2>Aucun élément</h2>
      <p>Commencez en créant votre premier élément</p>
      
      <div class="empty-actions">
        <q-btn unelevated color="primary" icon="add" label="Créer" @click="create" />
        <q-btn outline color="accent" icon="auto_awesome" label="Générer" @click="generate" />
      </div>
      
      <!-- Templates (optional) -->
      <div class="empty-templates">
        <div class="empty-templates__header">
          <q-icon name="lightbulb" />
          <span>Templates disponibles</span>
        </div>
        <div class="empty-templates__grid">
          <button 
            v-for="tpl in templates" 
            :key="tpl.id"
            class="template-card"
            @click="useTemplate(tpl)"
          >
            <q-icon :name="tpl.icon" size="24px" />
            <strong>{{ tpl.name }}</strong>
            <span>{{ tpl.desc }}</span>
          </button>
        </div>
      </div>
    </div>
  </div>
</template>
```

---

## 🎨 Design Tokens

### Colors (CSS Variables)
```scss
--q-primary          // Primary brand color
--q-accent           // Accent color
--q-positive         // Success green
--q-negative         // Error red
--q-warning          // Warning yellow
--q-info             // Info blue
--text-primary       // Main text
--text-secondary     // Muted text
--text-tertiary      // Hint text
--bg-elevated        // Card background
```

### Glass Morphism Pattern
```scss
.glass-card {
  background: color-mix(in srgb, var(--bg-elevated) 85%, transparent 15%);
  backdrop-filter: blur(20px) saturate(140%);
  border: 1px solid color-mix(in srgb, var(--accent-primary) 20%, transparent 80%);
  box-shadow: 
    0 8px 32px rgba(0, 0, 0, 0.4),
    inset 0 1px 0 color-mix(in srgb, white 8%, transparent 92%);
}
```

### Animations
```scss
// Standard timing
transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);

// Hover lift
&:hover {
  transform: translateY(-2px);
  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.15);
}

// Active press
&:active {
  transform: scale(0.98);
}
```

---

## 📊 Configuration Options

### Smart Notifications
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `message` | `string` | - | Notification text |
| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | `'default'` | Visual style |
| `priority` | `'low' \| 'normal' \| 'high' \| 'critical'` | `'normal'` | Affects timeout & position |
| `timeout` | `number` | Auto | Milliseconds before dismiss |
| `position` | `QNotifyPosition` | Auto | Screen position |
| `group` | `string` | - | Grouping key |
| `actions` | `NotificationAction[]` | `[]` | Action buttons |

### Quick Actions FAB
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `actions` | `QuickAction[]` | `[]` | Menu actions |
| `mainIcon` | `string` | `'add'` | FAB icon |
| `badge` | `string \| number` | - | Badge count |
| `position` | `'bottom-right' \| ...` | `'bottom-right'` | Screen position |
| `visible` | `boolean` | `true` | Show/hide |
| `closeOnAction` | `boolean` | `true` | Auto-close on click |
| `maxActions` | `number` | `6` | Max visible actions |

### Collaborative Cursors
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `presence` | `Presence[]` | `[]` | Active users |
| `inactivityTimeout` | `number` | `10000` | Hide after N ms |

---

## 🔧 TypeScript Types

```typescript
// Smart Notifications
interface NotificationAction {
  label: string
  color?: string
  icon?: string
  handler: () => void | Promise<void>
}

interface SmartNotifyOptions {
  message: string
  type?: 'success' | 'error' | 'warning' | 'info' | 'default'
  priority?: 'low' | 'normal' | 'high' | 'critical'
  timeout?: number
  position?: QNotifyCreateOptions['position']
  icon?: string
  actions?: NotificationAction[]
  group?: string
  avatar?: string
  progress?: boolean
  html?: boolean
  multiLine?: boolean
}

// Quick Actions FAB
interface QuickAction {
  id: string
  label: string
  subtitle?: string
  icon: string
  handler: () => void | Promise<void>
  disabled?: boolean
  loading?: boolean
  badge?: string | number
  badgeColor?: string
  priority?: number
}

// Collaborative Cursors
interface CollaborativeCursor {
  userId: string
  userName: string
  x: number
  y: number
  color: string
  lastUpdate: number
  visible: boolean
}
```

---

## 🎯 Priority Matrix

### Notification Priorities
```
Critical  →  Top center, never closes, red color
High      →  Top, 5s timeout, warning color
Normal    →  Top, 3s timeout, default color
Low       →  Bottom-right, 2s timeout, muted color
```

### FAB Action Priorities
```
Priority 3+  →  Always visible (top of menu)
Priority 2   →  Standard actions
Priority 1   →  Secondary actions
Priority 0   →  Hidden if menu full
```

---

## 📈 Performance Tips

### Smart Notifications
- ✅ Use `group` parameter to prevent spam
- ✅ Set appropriate `priority` for timeout
- ✅ Limit actions to 2-3 max
- ❌ Don't create >100 notifications per session

### Quick Actions FAB
- ✅ Set `maxActions` to limit menu size
- ✅ Use `priority` to show important actions first
- ✅ Hide FAB when dialogs are open
- ❌ Don't add more than 10 actions

### Collaborative Cursors
- ✅ Filter inactive users with `inactivityTimeout`
- ✅ Limit to active collaboration users only
- ❌ Don't render for >20 users

---

## 🐛 Troubleshooting

### Notifications not grouping
```typescript
// ❌ Wrong: Different messages
notify({ message: 'Plan saved', group: 'save' })
notify({ message: 'Plan updated', group: 'save' })

// ✅ Correct: Same group, similar message
notify({ message: 'Plan enregistré', group: 'save' })
notify({ message: 'Plan enregistré avec succès', group: 'save' })
```

### FAB menu cut off on small screens
```vue
<!-- ✅ Add max-actions prop -->
<QuickActionsFAB :actions="actions" :max-actions="4" />
```

### Cursors not appearing
```typescript
// ❌ Wrong: Missing presence prop
<CollaborativeCursors />

// ✅ Correct: Pass presence from collab
<CollaborativeCursors :presence="presence" />
```

---

## 📚 Related Docs

- **Full Guide**: `UX_IMPROVEMENTS_ADVANCED_COMPLETE.md`
- **Visual Summary**: `UX_IMPROVEMENTS_VISUAL_SUMMARY.md`
- **History Stack**: `docs/UNDO_REDO_GUIDE.md`
- **API Reference**: `docs/REFERENCE.md`

---

**Version**: 1.0.0  
**Last Updated**: November 4, 2025  
**Status**: ✅ Production Ready
