# Toast

轻量级全局消息提示，通过函数式调用触发，用于反馈操作结果。

> 这是一个基础消息组件，根据具体应用场景，你需要的可能是 Message 或 Notification 组件。

## 适用场景

- 操作成功、失败、警告的全局反馈提示
- 异步操作的 loading 状态显示与手动关闭
- 需要在不同屏幕位置展示的消息通知

## Props

### Toaster Props

> `Toaster` 是挂载在页面上的容器组件（通常无需手动使用）。

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| placement | `"top-center" \| "top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-center"` | 否 | 位置 |

### ToastOptions

> 调用 `toast()` / `toast.info()` 等函数时传入的选项。

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| id | `string` | `-` | 否 | 自定义 id |
| className | `string` | `-` | 否 | 自定义 class |
| type | `"info" \| "success" \| "warning" \| "error" \| "loading"` | `"info"` | 否 | 类型 |
| headline | `ReactNode` | `-` | 否 | 标题 |
| content | `ReactNode` | `-` | 否 | 内容 |
| duration | `number` | `3000` | 否 | 显示时长（ms）。`<= 0` 表示不自动关闭；正值小于最小值时会自动修正为最小值（3s） |
| onClose | `() => void` | `-` | 否 | 关闭回调 |
| manualClose | `boolean` | `false` | 否 | 是否显示手动关闭按钮（关闭小叉） |
| icon | `boolean \| SvgFC` | `-` | 否 | 图标。`false` 不使用，`true` 使用 theme 定义的图标集，或传入自定义 SvgFC |
| placement | `"top-center" \| "top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-center"` | 否 | 位置 |

## 典型用法

### 基础用法

```tsx
import { toast } from '@befe/brick'

toast.info('标题', '通知提示的文案')
toast.success('成功提示的文案')
toast.warning('警告提示的文案')
toast.error('错误提示的文案')
```

### Loading 状态（手动关闭）

```tsx
import { toast, removeToast, ToastObject } from '@befe/brick'

let currentToast: ToastObject | undefined

// 显示 loading，不自动关闭
currentToast = toast.warning('加载提示的文案', {
    duration: 0,
    type: 'loading',
    onClose: () => { currentToast = undefined },
})

// 手动关闭
removeToast(currentToast.id)
// 或
currentToast.remove()
```

### 指定位置

```tsx
import { toast, ToastOptions } from '@befe/brick'

toast({ headline: '消息标题', content: '内容', placement: 'top-left' })
toast({ headline: '消息标题', content: '内容', placement: 'top-right' })
toast({ headline: '消息标题', content: '内容', placement: 'bottom-left' })
toast({ headline: '消息标题', content: '内容', placement: 'bottom-right' })
```

### 样式隔离场景（createToast）

> 由于 `toast()` 在独立 root 渲染，ConfigProvider 的配置无法透传，需通过 `createToast` 传入 `wrapClassName` 等配置。

```tsx
import { createToast } from '@befe/brick'

const toast = createToast({ wrapClassName: 'awesome-one' })
toast.info('标题', '通知提示的文案')

// 或在组件内通过 hook 使用
function useToast() {
    const { wrapClassName } = useContext(ConfigContext)
    return createToast({ wrapClassName })
}
```

## 注意事项

- `duration` 小于最小值（目前 3s）的正值会被自动修正为 3s，这是设计规范约束，不可绕过
- `duration <= 0` 表示不自动关闭，需手动调用 `removeToast(id)` 或 `toastObject.remove()` 关闭
- `props.durationInMS` 已废弃，改用 `props.duration`
- `toast()` 在独立 DOM root 渲染，ConfigProvider 的 `wrapClassName` 等非单例配置不会自动透传，需使用 `createToast(configContext)` 手动传入