custom_ui/frontend/documentation/components/NotificationDisplay.md

# NotificationDisplay Component

The `NotificationDisplay` component provides a global notification system for displaying toast-style messages to users. It integrates seamlessly with the notification store to show success, error, warning, and info messages with optional action buttons.

## Overview

- **Location**: `src/components/common/NotificationDisplay.vue`
- **Type**: Global Component
- **Dependencies**: `@/stores/notifications`
- **Integration**: Added to `App.vue` for global usage

## Features

- ✅ **Multiple notification types** (success, error, warning, info)
- ✅ **Configurable positioning** (6 different positions)
- ✅ **Auto-dismiss with progress bars**
- ✅ **Persistent notifications**
- ✅ **Action buttons** with custom handlers
- ✅ **Smooth animations** (slide-in/out effects)
- ✅ **Responsive design**
- ✅ **Accessibility features**

## Usage

### Basic Integration

The component is automatically included in your application via `App.vue`:

```vue
<template>
  <div id="app">
    <!-- Your app content -->

    <!-- Global Notifications -->
    <NotificationDisplay />
  </div>
</template>
```

### Triggering Notifications

Use the notification store to display notifications:

```javascript
import { useNotificationStore } from "@/stores/notifications";

const notificationStore = useNotificationStore();

// Simple success notification
notificationStore.addSuccess("Data saved successfully!");

// Error notification
notificationStore.addError("Failed to save data", "Save Error");

// Custom notification with options
notificationStore.addNotification({
  type: "warning",
  title: "Unsaved Changes",
  message: "You have unsaved changes. What would you like to do?",
  persistent: true,
  actions: [
    {
      label: "Save",
      variant: "primary",
      handler: () => saveData(),
    },
    {
      label: "Discard",
      variant: "danger",
      handler: () => discardChanges(),
    },
  ],
});
```

## Notification Types

### Success

- **Color**: Green (#10b981)
- **Icon**: Check circle
- **Use case**: Successful operations, confirmations

### Error

- **Color**: Red (#ef4444)
- **Icon**: Alert circle
- **Default duration**: 6000ms (longer than others)
- **Use case**: Errors, failures, critical issues

### Warning

- **Color**: Orange (#f59e0b)
- **Icon**: Alert triangle
- **Use case**: Warnings, potential issues, confirmations needed

### Info

- **Color**: Blue (#3b82f6)
- **Icon**: Information circle
- **Use case**: General information, tips, status updates

## Positioning Options

The notification container can be positioned in 6 different locations:

```javascript
// Set position via notification store
notificationStore.setPosition("top-right"); // Default

// Available positions:
// - 'top-right'
// - 'top-left'
// - 'top-center'
// - 'bottom-right'
// - 'bottom-left'
// - 'bottom-center'
```

## Action Buttons

Notifications can include action buttons for user interaction:

```javascript
notificationStore.addNotification({
  type: "info",
  title: "File Upload",
  message: "File uploaded successfully. What would you like to do next?",
  actions: [
    {
      label: "View File",
      variant: "primary",
      icon: "mdi mdi-eye",
      handler: (notification) => {
        // Custom action logic
        console.log("Viewing file from notification:", notification);
      },
    },
    {
      label: "Share",
      variant: "secondary",
      icon: "mdi mdi-share",
      handler: () => shareFile(),
      dismissAfter: false, // Don't auto-dismiss after action
    },
  ],
});
```

### Action Button Variants

- **primary**: Blue background
- **danger**: Red background
- **secondary**: Gray background (default)

## Configuration Options

### Global Configuration

```javascript
const notificationStore = useNotificationStore();

// Set default duration (milliseconds)
notificationStore.setDefaultDuration(5000);

// Set maximum number of notifications
notificationStore.setMaxNotifications(3);

// Set position
notificationStore.setPosition("top-center");
```

### Per-Notification Options

```javascript
notificationStore.addNotification({
  type: 'success',
  title: 'Custom Notification',
  message: 'This notification has custom settings',

  // Duration (0 = no auto-dismiss)
  duration: 8000,

  // Persistent (won't auto-dismiss regardless of duration)
  persistent: false,

  // Custom actions
  actions: [...],

  // Additional data for handlers
  data: { userId: 123, action: 'update' }
});
```

## Responsive Behavior

The component automatically adapts to different screen sizes:

- **Desktop**: Fixed width (320px minimum, 400px maximum)
- **Mobile**: Full width with adjusted padding
- **Positioning**: Center positions become full-width on mobile

## Animations

The component includes smooth CSS transitions:

- **Enter**: Slide in from the appropriate direction
- **Leave**: Slide out in the same direction
- **Duration**: 300ms ease-out/ease-in
- **Progress Bar**: Animated countdown for timed notifications

## Accessibility Features

- **Keyboard Navigation**: Buttons are focusable and keyboard accessible
- **Screen Readers**: Proper ARIA labels and semantic HTML
- **Color Contrast**: High contrast colors for readability
- **Focus Management**: Proper focus indicators

## Styling

The component uses scoped CSS with CSS custom properties for easy customization:

```css
/* Custom styling example */
.notification-container {
  /* Override default styles */
  --notification-success-color: #059669;
  --notification-error-color: #dc2626;
  --notification-warning-color: #d97706;
  --notification-info-color: #2563eb;
}
```

## Best Practices

### Do's

- ✅ Use appropriate notification types for different scenarios
- ✅ Keep messages concise and actionable
- ✅ Use action buttons for common follow-up actions
- ✅ Set appropriate durations (longer for errors, shorter for success)
- ✅ Use persistent notifications for critical actions requiring user input

### Don'ts

- ❌ Don't show too many notifications at once (overwhelming)
- ❌ Don't use persistent notifications for simple confirmations
- ❌ Don't make notification messages too long
- ❌ Don't use error notifications for non-critical issues

## Integration with Error Store

The NotificationDisplay component works seamlessly with the Error Store:

```javascript
import { useErrorStore } from "@/stores/errors";

const errorStore = useErrorStore();

// Errors automatically trigger notifications
await errorStore.withErrorHandling(
  "api-call",
  async () => {
    // Your async operation
  },
  {
    componentName: "myComponent",
    showNotification: true, // Automatically shows error notifications
  },
);
```

## Examples

### Basic Usage Examples

```javascript
const notificationStore = useNotificationStore();

// Simple notifications
notificationStore.addSuccess("Changes saved!");
notificationStore.addError("Network connection failed");
notificationStore.addWarning("Unsaved changes detected");
notificationStore.addInfo("New feature available");

// Advanced notification with multiple actions
notificationStore.addNotification({
  type: "warning",
  title: "Confirm Deletion",
  message: "This action cannot be undone. Are you sure?",
  persistent: true,
  actions: [
    {
      label: "Delete",
      variant: "danger",
      handler: () => {
        performDeletion();
        notificationStore.addSuccess("Item deleted successfully");
      },
    },
    {
      label: "Cancel",
      variant: "secondary",
    },
  ],
});
```

### API Integration Examples

```javascript
// Show loading notification that updates on completion
const loadingId =
  notificationStore.showLoadingNotification("Uploading file...");

try {
  await uploadFile();
  notificationStore.updateToSuccess(loadingId, "File uploaded successfully!");
} catch (error) {
  notificationStore.updateToError(loadingId, "Upload failed: " + error.message);
}
```

## Troubleshooting

### Common Issues

1. **Notifications not appearing**
   - Ensure NotificationDisplay is included in App.vue
   - Check z-index conflicts with other components
   - Verify notification store is properly imported

2. **Notifications appearing in wrong position**
   - Check the position setting in the store
   - Verify CSS is not being overridden

3. **Action buttons not working**
   - Ensure handler functions are properly defined
   - Check for JavaScript errors in handlers

### Debug Mode

Enable debug logging in development:

```javascript
// In your main.js or component
if (process.env.NODE_ENV === "development") {
  const notificationStore = useNotificationStore();
  // Watch for notification changes
  watch(
    () => notificationStore.notifications,
    (notifications) => {
      console.log("Notifications updated:", notifications);
    },
  );
}
```