noob-components/.trellis/spec/plugs-element/message.md

# message

> Element Plus message/notification/loading wrappers with i18n support.

## Source

**File**: `plugs/element/message.ts`

---

## Overview

Provides layered wrappers around Element Plus UI components:
- `ElLoading` - Full-screen loading overlay
- `ElMessage` - Toast notifications
- `ElNotification` - Corner notifications
- `ElMessageBox` - Confirm dialogs and prompts

All functions use i18n for text content via `plugs/i18n`.

---

## Loading Overlay

### Function: loading

Shows a full-screen loading overlay with reference counting.

```typescript
export function loading(): void
```

### Function: close

Decrements counter and closes overlay when count reaches zero.

```typescript
export function close(): void
```

### Reference Counting Pattern

```typescript
import { loading, close } from 'plugs/element/message';

// Show loading
loading();  // count = 1
loading();  // count = 2

// Hide loading
close();    // count = 1
close();    // count = 0, overlay closes
```

### Options Used

```typescript
{
  lock: true,
  text: t('base.loading'),        // i18n key for loading text
  spinner: 'el-icon-loading',
  background: 'rgba(0, 0, 0, 0.3)'
}
```

---

## Toast Messages

### Function: showMessage

Internal function for `warning`, `error`, `success` shortcuts.

```typescript
export function showMessage(type: string, info: any, unClose?: boolean): void
```

| Parameter | Description |
|-----------|-------------|
| `type` | Message type: `'warning'`, `'error'`, `'success'`, `'info'` |
| `info` | Message content |
| `unClose` | If `true`, does not replace previous message |

### Message Shortcuts

```typescript
export function warning(msg: string): void
export function error(msg: string): void
export function success(msg: string): void
```

### Usage

```typescript
import { success, error, warning } from 'plugs/element/message';

success('Operation completed');
error('Something went wrong');
warning('Please check your input');
```

### Options Used

```typescript
{
  type: type,
  showClose: true,
  message: info,
  duration: 3000,
  offset: 50
}
```

---

## Notifications

### Function: showNotify

Shows a corner notification (top-right by default).

```typescript
export function showNotify(type: string, title: string, message: string, position?: string): void
```

### Usage

```typescript
import { showNotify } from 'plugs/element/message';

showNotify('success', 'Saved', 'Your changes have been saved');
showNotify('error', 'Error', 'Failed to load data', 'bottom-right');
```

### Options Used

```typescript
{
  title: title,
  type: type,
  message: message,
  position: position || 'top-right',
  duration: 0  // Does not auto-dismiss
}
```

---

## MessageBox Dialogs

### Function: confirm

Shows a confirmation dialog with OK/Cancel buttons.

```typescript
export const confirm = (msg: string, title: string): Promise<boolean>
```

### Usage

```typescript
import { confirm } from 'plugs/element/message';

const isConfirmed = await confirm('Are you sure?', 'Confirm Action');
if (isConfirmed) {
  // User clicked OK
}
```

### Options Used

```typescript
{
  confirmButtonText: t('base.confirm'),
  cancelButtonText: t('base.cancel'),
  buttonSize: 'default',
  confirmButtonClass: 'el-button--info',
  type: 'warning'
}
```

### Promise Behavior

- Resolves `true` on confirm
- Resolves `false` on cancel (or any dismissal)
- Never rejects

---

### Function: prompt

Shows an input dialog with validation.

```typescript
export const prompt = (
  msg: string,
  title: string,
  pattern: RegExp,
  errorMsg: string
): Promise<string | false>
```

### Usage

```typescript
import { prompt } from 'plugs/element/message';

const result = await prompt(
  'Enter your email',
  'Email Verification',
  /^([a-zA-Z0-9_\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$/,
  'Invalid email format'
);

// result is the input value (string) or false if cancelled
```

### Options Used

```typescript
{
  confirmButtonText: t('base.confirm'),
  cancelButtonText: t('base.cancel'),
  buttonSize: 'default',
  confirmButtonClass: 'el-button--info',
  inputPattern: pattern,
  inputErrorMessage: errorMsg
}
```

### Promise Behavior

- Resolves with input `value` on submit
- Resolves `false` on cancel
- Never rejects

---

## Imports

```typescript
import { ElLoading, ElMessage, ElNotification, ElMessageBox } from 'element-plus';
import { i18n } from '../i18n';
const t = i18n.t;
```

---

## Related

- `plugs/element/index.ts` exports icons array
- Uses `plugs/i18n` for localization
- Built on Element Plus components