@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/feedback/Toast.d.ts

@@ -0,0 +1,204 @@
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import { type VNodeChild } from 'vue';
+import type { IconData } from '../base/Icon';
+import { type CollapseProps } from '../display/Collapse';
+import { type PartProps } from '../utils/props';
+import type { StatusTone } from '../utils/style/tone-styles';
+import { type AlertProps } from './Alert';
+import { type FlexProps } from '../layout/Flex';
+/** 一条通知的内容与行为 */
+export interface ToastOptions {
+    /** 标题（加粗的第一行） */
+    title?: VNodeChild;
+    /** 正文 */
+    description?: VNodeChild;
+    /** 色调，默认 neutral */
+    tone?: StatusTone;
+    /** 图标；不写时按色调选，false 不显示 */
+    icon?: IconData | false;
+    /** 进行中：图标换成加载指示，不自动消失 */
+    loading?: boolean;
+    /** 右侧的操作（如“撤销”按钮） */
+    action?: VNodeChild;
+    /** 显示关闭按钮，默认 true */
+    closable?: boolean;
+    /** 显示多久（毫秒）后自动消失；Infinity 不自动消失；不写时用 createToaster 的默认值 */
+    duration?: number;
+    /** 重要：读屏立即打断播报（aria-live="assertive"），用于出错、需要马上处理的通知；默认按礼貌的顺序念 */
+    important?: boolean;
+    /** 编号：同一个编号的通知只有一条，再 show 时换掉它；不写时自动生成 */
+    id?: string;
+    /** 开始关闭时调用（自动消失或被关闭）；同一条通知只调用一次 */
+    onClose?: (reason: keyof ToastCloseReasons) => void;
+}
+/** 快捷方法的选项：标题由第一个参数给出 */
+export type ToastShortcutOptions = Omit<ToastOptions, 'title' | 'tone'>;
+/** 通知为什么关闭 */
+export interface ToastCloseReasons {
+    /** 到时间自动消失 */
+    timeout: unknown;
+    /** 用户点了关闭、滑走、按了 Esc，或代码调用了 dismiss */
+    dismissed: unknown;
+}
+/** 列表里的一条通知 */
+export interface ToastRecord extends ToastOptions {
+    /** show 返回的编号 */
+    readonly id: string;
+    /** 正在离场（已关闭，等离场过渡结束后移除） */
+    readonly closing: boolean;
+    /** 本轮自动关闭的计时：总时长（毫秒）与编号（重新计时时换一个）；不自动关闭（加载中、Infinity）时为 null */
+    readonly countdown: {
+        readonly duration: number;
+        readonly id: number;
+    } | null;
+}
+/** promise 各阶段的通知：固定内容，或由结果算出 */
+export type ToastMessage<T> = ToastOptions | ((value: T) => ToastOptions);
+/** toaster.promise 的三个阶段 */
+export interface ToastPromiseMessages<T> {
+    /** 进行中（自动带上 loading） */
+    loading: ToastOptions;
+    /** 成功，默认色调 success */
+    success: ToastMessage<T>;
+    /** 失败，默认色调 danger */
+    error: ToastMessage<unknown>;
+}
+/** createToaster 的选项 */
+export interface ToasterOptions {
+    /** 默认显示时长（毫秒），默认 5000 */
+    duration?: number;
+}
+/** 通知控制器：createToaster() 创建，交给 <Toaster controller>，在任何地方调用 */
+export interface ToasterController {
+    /** 当前的通知，旧的在前 */
+    readonly toasts: readonly ToastRecord[];
+    /** 计时是否暂停（悬停、聚焦、页面隐藏时） */
+    readonly paused: boolean;
+    /** 显示一条通知，返回它的编号；options.id 已有时换掉那一条（不与它合并） */
+    show(options: ToastOptions): string;
+    /** 成功的通知：`toaster.success('已保存')` */
+    success(title: VNodeChild, options?: ToastShortcutOptions): string;
+    /** 出错的通知（读屏立即播报） */
+    error(title: VNodeChild, options?: ToastShortcutOptions): string;
+    /** 警告的通知 */
+    warning(title: VNodeChild, options?: ToastShortcutOptions): string;
+    /** 提示的通知 */
+    info(title: VNodeChild, options?: ToastShortcutOptions): string;
+    /** 进行中的通知（不自动消失）：完成后用同一个 id 调 success / error 换掉它，或 dismiss */
+    loading(title: VNodeChild, options?: ToastShortcutOptions): string;
+    /** 改一条通知的内容（如加载完成）；计时按新的 duration 重新开始 */
+    update(id: string, options: ToastOptions): void;
+    /** 关闭一条通知；不给编号时关闭全部 */
+    dismiss(id?: string): void;
+    /** 进行中 → 成功 / 失败：同一条通知依次更新；返回原 Promise 的结果（失败时照样抛出） */
+    promise<T>(promise: Promise<T>, messages: ToastPromiseMessages<T>): Promise<T>;
+    /** 暂停 / 继续所有通知的计时：Toaster 在悬停、聚焦、页面隐藏时调用 */
+    pause(): void;
+    /** 继续计时，见 pause */
+    resume(): void;
+    /** 从列表里移除（Toaster 在离场过渡结束后调用；直接调用则没有离场动画） */
+    remove(id: string): void;
+    /** 最多显示几条（Toaster 的 max）：只给显示出来的通知计时，没轮到的等它出现再开始 */
+    setLimit(limit: number): void;
+}
+/** 创建通知控制器 */
+export declare function createToaster({ duration: defaultDuration, }?: ToasterOptions): ToasterController;
+/** 通知显示在视口的哪个位置 */
+export interface ToastPlacements {
+    /** 左上（从右到左排版时右上） */
+    'top-start': unknown;
+    /** 顶部居中 */
+    top: unknown;
+    /** 右上（从右到左排版时左上） */
+    'top-end': unknown;
+    /** 左下（从右到左排版时右下） */
+    'bottom-start': unknown;
+    /** 底部居中 */
+    bottom: unknown;
+    /** 右下（默认；从右到左排版时左下） */
+    'bottom-end': unknown;
+}
+/** 未声明的属性落到区域（section）上；aria-label 默认取语言包（通知） */
+export interface ToasterProps extends PartProps<'section', 'popover' | 'tabindex'> {
+    /** createToaster() 创建的控制器 */
+    controller: ToasterController;
+    /** 显示位置，默认 bottom-end */
+    placement?: keyof ToastPlacements;
+    /** 最多同时显示几条，默认 3；更早的先不显示，前面的关闭后补上 */
+    max?: number;
+    /** 叠成一摞（同 Sonner）：只露出最新的一条，更早的缩小叠在后面；悬停或聚焦时展开，展开收起有布局动画。默认 false（平铺） */
+    stack?: boolean;
+    /** 在自动关闭的通知底部显示剩余时间条（暂停计时时一起停），默认 false */
+    progress?: boolean;
+    /** 列表（ol）的部件属性 */
+    propsList?: Omit<Partial<FlexProps<'ol'>>, 'aria-live'>;
+    /** 每一项（li）的部件属性 */
+    propsItem?: PartProps<'li'> | ((toast: ToastRecord) => PartProps<'li'>);
+    /** 每条通知（Alert）的部件属性 */
+    propsToast?: Partial<AlertProps> | ((toast: ToastRecord) => Partial<AlertProps>);
+    /** 剩余时间条的部件属性 */
+    propsProgress?: PartProps<'span'>;
+    /** 每一项里收起高度的 Collapse 的部件属性（离场时它收起，下面的通知补上来） */
+    propsCollapse?: Partial<CollapseProps>;
+}
+/** Toaster 的样式：region、list、listFromTop、item、itemFromBottom、itemFromTop 等 */
+export declare const toastStyles: Readonly<{
+    countdown: css.CompiledStyles;
+    countdownPaused: css.CompiledStyles;
+    gap: css.CompiledStyles;
+    item: css.CompiledStyles;
+    itemClosing: css.CompiledStyles;
+    itemFromBottom: css.CompiledStyles;
+    itemFromTop: css.CompiledStyles;
+    region: css.CompiledStyles;
+    stacked: css.CompiledStyles;
+    stackedBehind: css.CompiledStyles;
+    stackedFromBottom: css.CompiledStyles;
+    stackedFromTop: css.CompiledStyles;
+    stackedHidden: css.CompiledStyles;
+    toast: css.CompiledStyles;
+}>;
+/** Toaster 的样式：叠放时第 depth 层（0 是最新的）的位移、缩放与层叠顺序 */
+export declare const toastStackStyles: Readonly<{
+    readonly depth: (offset: string, scale: number, zIndex: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+}>;
+/** Toaster 的样式：剩余时间条的时长 */
+export declare const toastCountdownStyles: Readonly<{
+    readonly duration: (ms: string) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+}>;
+/** Toaster 的样式：top-start、top、top-end、bottom-start、bottom、bottom-end */
+export declare const toastPlacementStyles: Readonly<{
+    bottom: css.CompiledStyles;
+    "bottom-end": css.CompiledStyles;
+    "bottom-start": css.CompiledStyles;
+    top: css.CompiledStyles;
+    "top-end": css.CompiledStyles;
+    "top-start": css.CompiledStyles;
+}>;
+/** Toaster 里每条通知的 props */
+export interface ToastItemProps {
+    /** 这条通知 */
+    toast: ToastRecord;
+    /** 所属的通知器：关闭、暂停计时 */
+    controller: ToasterController;
+    /** Toaster 在顶部：进场从上方滑入 */
+    fromTop: boolean;
+    /** 最后一条被关闭时焦点回到这里 */
+    fallbackFocus: () => HTMLElement | null;
+    /** 每条通知外层（li）的部件属性 */
+    propsItem: ToasterProps['propsItem'];
+    /** 通知本身（Alert）的部件属性 */
+    propsToast: ToasterProps['propsToast'];
+    /** 叠放时的深度（0 是最新的一条）；平铺或展开时为 null */
+    depth: number | null;
+    /** 显示剩余时间条 */
+    progress: boolean;
+    /** 剩余时间条的部件属性 */
+    propsProgress: ToasterProps['propsProgress'];
+    /** 收起高度的 Collapse 的部件属性 */
+    propsCollapse: ToasterProps['propsCollapse'];
+}
+/** 列表里的一项：Collapse 负责离场时收起高度，收起后从控制器里移除 */
+export declare const ToastItem: import("@zerodep-dev/vue-tsx-pro-tsx").TsxComponent<ToastItemProps>;
+/** 通知的显示区域：放一个即可；模态打开时自动移进最上层的模态 */
+export declare const Toaster: import("@zerodep-dev/vue-tsx-pro-tsx").TsxComponent<ToasterProps>;