custom_ui/frontend/documentation/components/Modal.md

# Dynamic Modal Component Documentation

## Overview

A flexible and customizable modal component built with Vuetify's v-dialog. This component provides extensive configuration options and supports slot-based content rendering.

## Basic Usage

```vue
<template>
  <Modal
    v-model:visible="isModalVisible"
    :options="modalOptions"
    @close="handleClose"
    @confirm="handleConfirm"
  >
    <p>Your modal content goes here</p>
  </Modal>
</template>

<script setup>
import { ref } from 'vue'
import Modal from './components/Modal.vue'

const isModalVisible = ref(false)
const modalOptions = {
  title: 'My Modal',
  maxWidth: '500px'
}

const handleClose = () => {
  console.log('Modal closed')
}

const handleConfirm = () => {
  console.log('Modal confirmed')
}
</script>
```

## Props

### `visible` (Boolean)
- **Default:** `false`
- **Description:** Controls the visibility state of the modal
- **Usage:** Use with `v-model:visible` for two-way binding

### `options` (Object)
- **Default:** `{}`
- **Description:** Configuration object for customizing modal behavior and appearance

## Options Object Properties

### Dialog Configuration
- **`persistent`** (Boolean, default: `false`) - Prevents closing when clicking outside or pressing escape
- **`fullscreen`** (Boolean, default: `false`) - Makes the modal fullscreen
- **`maxWidth`** (String, default: `'500px'`) - Maximum width of the modal
- **`width`** (String) - Fixed width of the modal
- **`height`** (String) - Fixed height of the modal
- **`attach`** (String) - Element to attach the modal to
- **`transition`** (String, default: `'dialog-transition'`) - CSS transition name
- **`scrollable`** (Boolean, default: `false`) - Makes the modal content scrollable
- **`retainFocus`** (Boolean, default: `true`) - Retains focus within the modal
- **`closeOnBack`** (Boolean, default: `true`) - Closes modal on browser back button
- **`closeOnContentClick`** (Boolean, default: `false`) - Closes modal when clicking content
- **`closeOnOutsideClick`** (Boolean, default: `true`) - Closes modal when clicking outside
- **`closeOnEscape`** (Boolean, default: `true`) - Closes modal when pressing escape key

### Styling Options
- **`overlayColor`** (String) - Color of the backdrop overlay
- **`overlayOpacity`** (Number) - Opacity of the backdrop overlay
- **`zIndex`** (Number) - Z-index of the modal
- **`dialogClass`** (String) - Additional CSS classes for the dialog
- **`cardClass`** (String) - Additional CSS classes for the card
- **`cardColor`** (String) - Background color of the card
- **`cardVariant`** (String) - Vuetify card variant
- **`elevation`** (Number) - Shadow elevation of the card
- **`flat`** (Boolean) - Removes elevation
- **`noRadius`** (Boolean) - Removes border radius

### Header Configuration
- **`title`** (String) - Modal title text
- **`showHeader`** (Boolean, default: `true`) - Shows/hides the header
- **`showHeaderDivider`** (Boolean) - Shows divider below header
- **`headerClass`** (String) - Additional CSS classes for header
- **`showCloseButton`** (Boolean, default: `true`) - Shows/hides close button
- **`closeButtonColor`** (String, default: `'grey'`) - Color of close button
- **`closeIcon`** (String, default: `'mdi-close'`) - Icon for close button

### Content Configuration
- **`message`** (String) - Default message content (HTML supported)
- **`contentClass`** (String) - Additional CSS classes for content area
- **`contentHeight`** (String) - Fixed height of content area
- **`contentMaxHeight`** (String) - Maximum height of content area
- **`contentMinHeight`** (String) - Minimum height of content area
- **`noPadding`** (Boolean) - Removes padding from content area

### Actions Configuration
- **`showActions`** (Boolean, default: `true`) - Shows/hides action buttons
- **`actionsClass`** (String) - Additional CSS classes for actions area
- **`actionsAlign`** (String) - Alignment of action buttons (`'left'`, `'center'`, `'right'`, `'space-between'`)

### Button Configuration
- **`showConfirmButton`** (Boolean, default: `true`) - Shows/hides confirm button
- **`confirmButtonText`** (String, default: `'Confirm'`) - Text for confirm button
- **`confirmButtonColor`** (String, default: `'primary'`) - Color of confirm button
- **`confirmButtonVariant`** (String, default: `'elevated'`) - Variant of confirm button
- **`showCancelButton`** (Boolean, default: `true`) - Shows/hides cancel button
- **`cancelButtonText`** (String, default: `'Cancel'`) - Text for cancel button
- **`cancelButtonColor`** (String, default: `'grey'`) - Color of cancel button
- **`cancelButtonVariant`** (String, default: `'text'`) - Variant of cancel button
- **`loading`** (Boolean) - Shows loading state on confirm button

### Behavior Configuration
- **`autoCloseOnConfirm`** (Boolean, default: `true`) - Auto-closes modal after confirm
- **`autoCloseOnCancel`** (Boolean, default: `true`) - Auto-closes modal after cancel
- **`onOpen`** (Function) - Callback function when modal opens
- **`onClose`** (Function) - Callback function when modal closes

## Events

- **`update:visible`** - Emitted when visibility state changes
- **`close`** - Emitted when modal is closed
- **`confirm`** - Emitted when confirm button is clicked
- **`cancel`** - Emitted when cancel button is clicked
- **`outside-click`** - Emitted when clicking outside the modal
- **`escape-key`** - Emitted when escape key is pressed

## Slots

### Default Slot
```vue
<Modal>
  <p>Your content here</p>
</Modal>
```

### Title Slot
```vue
<Modal>
  <template #title>
    <v-icon class="mr-2">mdi-account</v-icon>
    Custom Title
  </template>
</Modal>
```

### Actions Slot
```vue
<Modal>
  <template #actions="{ close, options }">
    <v-btn @click="customAction">Custom Action</v-btn>
    <v-btn @click="close">Close</v-btn>
  </template>
</Modal>
```

## Usage Examples

### Basic Modal
```vue
const basicOptions = {
  title: 'Information',
  maxWidth: '400px'
}
```

### Confirmation Modal
```vue
const confirmOptions = {
  title: 'Confirm Action',
  persistent: false,
  confirmButtonText: 'Delete',
  confirmButtonColor: 'error',
  cancelButtonText: 'Keep'
}
```

### Form Modal
```vue
const formOptions = {
  title: 'Add New Item',
  maxWidth: '600px',
  persistent: true,
  confirmButtonText: 'Save',
  loading: isLoading.value
}
```

### Fullscreen Modal
```vue
const fullscreenOptions = {
  fullscreen: true,
  showActions: false,
  scrollable: true
}
```

### Custom Styled Modal
```vue
const customOptions = {
  maxWidth: '500px',
  cardColor: 'primary',
  elevation: 12,
  overlayOpacity: 0.8,
  transition: 'scale-transition'
}
```

## Advanced Usage

### With Reactive Options
```vue
<script setup>
import { ref, computed } from 'vue'

const loading = ref(false)
const formValid = ref(false)

const modalOptions = computed(() => ({
  title: 'Dynamic Title',
  loading: loading.value,
  confirmButtonText: formValid.value ? 'Save' : 'Validate First',
  persistent: !formValid.value
}))
</script>
```

### Multiple Modals
```vue
<template>
  <!-- Each modal can have different configurations -->
  <Modal v-model:visible="modal1" :options="options1">
    Content 1
  </Modal>
  
  <Modal v-model:visible="modal2" :options="options2">
    Content 2
  </Modal>
</template>
```

## Best Practices

1. **Use persistent modals for forms** to prevent accidental data loss
2. **Set appropriate maxWidth** for different screen sizes
3. **Use loading states** for async operations
4. **Provide clear button labels** that describe the action
5. **Use slots for complex content** instead of the message option
6. **Handle all events** to provide good user feedback
7. **Test keyboard navigation** and accessibility features

## Responsive Behavior

The modal automatically adjusts for mobile devices:
- Reduced padding on smaller screens
- Appropriate font sizes
- Touch-friendly button sizes
- Proper viewport handling

## Accessibility

The component includes:
- Proper ARIA attributes
- Keyboard navigation support
- Focus management
- Screen reader compatibility
- High contrast support