@icen.ai/ui 0.4.0 → 0.8.0

package/dist/behaviors/notification.d.mts

@@ -0,0 +1,172 @@
+type NotificationKind = 'success' | 'warning' | 'error' | 'info';
+interface NotificationAction {
+    /** 按钮文字 */
+    label: string;
+    /** 点击回调；返回 false 阻止通知关闭 */
+    onClick?: () => void | Promise<void> | boolean;
+    /** 视觉变体：默认 ghost / primary 实底 / danger 危险色 */
+    type?: 'primary' | 'ghost' | 'danger';
+    /** 点击后是否保持通知打开（默认 false） */
+    keepOpen?: boolean;
+}
+interface NotificationOptions {
+    /** 显式 id（不传自动生成；用于后续 update/dismiss/get） */
+    id?: string;
+    /** 副标题（正文） */
+    description?: string;
+    /** 自动关闭延时（毫秒），默认 0 = 不自动关闭 */
+    duration?: number;
+    /** 是否显示关闭按钮，默认 true */
+    closable?: boolean;
+    /** hover 时暂停自动关闭倒计时，默认跟随全局 config.pauseOnHover */
+    pauseOnHover?: boolean;
+    /** duration > 0 时是否显示底部倒计时进度条，默认 true */
+    showCountdown?: boolean;
+    /** 自定义图标：SVG 字符串 / 图片 URL / false（关闭） */
+    icon?: string | false;
+    /** 头像 URL（会覆盖 kind 图标） */
+    avatar?: string;
+    /** 优先级：normal（默认）/ high（置顶） */
+    priority?: 'normal' | 'high';
+    /** 未读标记，默认 false（push 后可 markRead） */
+    unread?: boolean;
+    /** 多动作按钮（actions 优先于 actionLabel） */
+    actions?: NotificationAction[];
+    /** 兼容旧版单按钮 */
+    actionLabel?: string;
+    onAction?: () => void | Promise<void> | boolean;
+    /** 进度（0–1）；progress > 0 时显示进度条。推荐用 notify.progress() 返回的 handle.setProgress */
+    progress?: number;
+    /** 进度条下方文字（如「正在导出 64%」） */
+    progressLabel?: string;
+    /** 详情链接（绝对 / 相对路径） */
+    link?: string;
+    linkLabel?: string;
+    /** 分组键：同 tag 的多条会聚合显示计数 */
+    tag?: string;
+    /** 自定义数据（持久化时保留） */
+    data?: unknown;
+    /** 点击通知体的回调（不含按钮与关闭） */
+    onClick?: (handle: NotificationHandle) => void;
+    /** 显示后回调 */
+    onShow?: (handle: NotificationHandle) => void;
+    /** 关闭后回调 */
+    onClose?: (handle: NotificationHandle) => void;
+}
+interface NotificationConfig {
+    /** 位置：top-right（默认）/ top-left / bottom-left / bottom-right */
+    position?: 'top-right' | 'top-left' | 'bottom-left' | 'bottom-right';
+    /** 同屏最大堆叠，默认 5；超出从最早的开始折叠/移除 */
+    maxStack?: number;
+    /** hover 暂停倒计时，默认 true */
+    pauseOnHover?: boolean;
+    /** 持久化：true 用默认 key / 字符串=自定义 key / 不传=不持久化 */
+    persist?: boolean | string;
+    /** 声音提示：true 用默认蜂鸣 / 字符串=data URL / 不传=无声 */
+    sound?: boolean | string;
+}
+interface NotificationHandle {
+    /** 通知 id */
+    id: string;
+    /** 当前 DOM 元素（可能已脱离 DOM） */
+    el: HTMLElement;
+    /** 关闭本条 */
+    dismiss(): void;
+    /** 部分更新（title / description / progress / unread / actions / tag 等） */
+    update(patch: NotificationUpdatePatch): void;
+    /** 设置进度（0–1）与可选标签 */
+    setProgress(value: number, label?: string): void;
+    /** 标记已读 */
+    markRead(): void;
+    /** 暂停自动关闭倒计时 */
+    pause(): void;
+    /** 恢复自动关闭倒计时（继续剩余时间） */
+    resume(): void;
+}
+/** update 接受的局部字段（title 在 push 时传，update 时也接受） */
+interface NotificationUpdatePatch {
+    title?: string;
+    description?: string;
+    duration?: number;
+    unread?: boolean;
+    progress?: number;
+    progressLabel?: string;
+    actions?: NotificationAction[];
+    tag?: string;
+    priority?: 'normal' | 'high';
+    icon?: string | false;
+    avatar?: string;
+    link?: string;
+    linkLabel?: string;
+}
+interface NotificationRecord {
+    id: string;
+    title: string;
+    kind: NotificationKind;
+    opts: NotificationOptions;
+    el: HTMLElement | null;
+    createdAt: number;
+    duration: number;
+    remaining: number;
+    paused: boolean;
+    timer: number;
+    /** 本次计时的起始时间戳（pause 时据此扣减 remaining） */
+    startedAt: number;
+    /** 所属 NotificationCenter 的局部配置（全局单例通知为 undefined） */
+    cfgRef?: Required<NotificationConfig>;
+    /** 所属 center 的 localStore（全局通知为 undefined）；dismiss 时同步清理，避免残留僵尸记录 */
+    ownerStore?: Map<string, NotificationRecord>;
+    /** attachTimer 注入的重启入口（update duration 时按新时长重启计时） */
+    restartTimer?: () => void;
+    /** hover 暂停监听是否已绑定（attachTimer 幂等保护） */
+    hoverBound?: boolean;
+}
+interface NotifyFn {
+    (title: string, opts?: NotificationOptions): NotificationHandle | null;
+    success(title: string, opts?: NotificationOptions): NotificationHandle | null;
+    warn(title: string, opts?: NotificationOptions): NotificationHandle | null;
+    error(title: string, opts?: NotificationOptions): NotificationHandle | null;
+    info(title: string, opts?: NotificationOptions): NotificationHandle | null;
+    progress(title: string, opts?: NotificationOptions): NotificationHandle | null;
+    confirm(title: string, opts?: NotificationConfirmOptions): Promise<boolean>;
+    dismiss(id?: string): void;
+    clear(): void;
+    markRead(id?: string): void;
+    update(id: string, patch: NotificationUpdatePatch): void;
+    get(id: string): NotificationRecord | null;
+    getAll(): NotificationRecord[];
+    config(opts: NotificationConfig): void;
+}
+interface NotificationConfirmOptions extends Omit<NotificationOptions, 'actions' | 'duration' | 'closable'> {
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** 自动关闭毫秒（默认 0 = 不自动关闭） */
+    duration?: number;
+}
+interface NotificationCenterHandle {
+    push(notif: NotificationPushInput): NotificationHandle | null;
+    dismiss(id?: string): void;
+    clear(): void;
+    markAllRead(): void;
+    /** 销毁容器：移除 DOM、清掉其所有 timer 与监听器；之后 push 返回 null */
+    destroy(): void;
+    get(id: string): NotificationRecord | null;
+    getAll(): NotificationRecord[];
+    config(opts: NotificationConfig): void;
+    el: HTMLElement;
+}
+interface NotificationPushInput {
+    title: string;
+    kind?: NotificationKind;
+    options?: NotificationOptions;
+}
+/**
+ * 创建一个独立的通知中心容器（可同时存在多个，比如顶部=警告、右下=消息）。
+ * 注意：默认全局 notify.* 走单例容器，与本函数创建的额外容器并存。
+ */
+declare function createNotificationCenter(parent?: ParentNode, opts?: NotificationConfig): NotificationCenterHandle;
+declare const notify: NotifyFn;
+/** 委托初始化：建立默认容器 + 恢复持久化通知。幂等。 */
+declare function initNotification(): void;
+
+export { type NotificationAction, type NotificationCenterHandle, type NotificationConfig, type NotificationConfirmOptions, type NotificationHandle, type NotificationKind, type NotificationOptions, type NotificationPushInput, type NotificationUpdatePatch, createNotificationCenter, initNotification, notify };