@zag-js/toast 0.82.1 → 1.0.0

package/dist/index.d.mts

@@ -1,23 +1,30 @@
-import { CommonProperties, Direction, RequiredBy, PropTypes, DirectionProperty, NormalizeProps } from '@zag-js/types';
 import * as _zag_js_core from '@zag-js/core';
-import { Machine, StateMachine } from '@zag-js/core';
+import { Service, EventObject } from '@zag-js/core';
+import { CommonProperties, Direction, DirectionProperty, Required, PropTypes, RequiredBy, NormalizeProps } from '@zag-js/types';
 import * as _zag_js_anatomy from '@zag-js/anatomy';
 
 type Type = "success" | "error" | "loading" | "info" | (string & {});
 type Placement = "top-start" | "top" | "top-end" | "bottom-start" | "bottom" | "bottom-end";
 type Status = "visible" | "dismissing" | "unmounted";
-interface GenericOptions<T = string> {
+interface StatusChangeDetails {
     /**
-     * The title of the toast.
+     * The status of the toast
      */
-    title?: T | undefined;
+    status: Status;
     /**
-     * The description of the toast.
+     * The reason for the status change
      */
-    description?: T | undefined;
+    src?: string | undefined;
 }
-interface StatusChangeDetails {
-    status: Status;
+interface ToastHeight {
+    /**
+     * The id of the toast
+     */
+    id: string;
+    /**
+     * The height of the toast
+     */
+    height: number;
 }
 interface ActionOptions {
     /**
@@ -29,7 +36,15 @@ interface ActionOptions {
      */
     onClick: () => void;
 }
-interface Options<T> extends GenericOptions<T> {
+interface Options<T = any> {
+    /**
+     * The title of the toast.
+     */
+    title?: T | undefined;
+    /**
+     * The description of the toast.
+     */
+    description?: T | undefined;
     /**
      * The duration the toast will be visible
      */
@@ -39,10 +54,6 @@ interface Options<T> extends GenericOptions<T> {
      * Useful for exit transitions.
      */
     removeDelay?: number | undefined;
-    /**
-     * The placement of the toast
-     */
-    placement?: Placement | undefined;
     /**
      * The unique id of the toast
      */
@@ -54,202 +65,249 @@ interface Options<T> extends GenericOptions<T> {
     /**
      * Function called when the toast is visible
      */
-    onStatusChange?(details: StatusChangeDetails): void;
+    onStatusChange?: ((details: StatusChangeDetails) => void) | undefined;
     /**
      * The action of the toast
      */
     action?: ActionOptions | undefined;
+    /**
+     * Whether the toast is closable
+     */
+    closable?: boolean | undefined;
     /**
      * The metadata of the toast
      */
     meta?: Record<string, any> | undefined;
 }
-interface MachineContext<T = any> extends Omit<CommonProperties, "id">, MachinePrivateContext, Omit<Options<T>, "removeDelay"> {
+interface ToastProps<T = any> extends Omit<CommonProperties, "id">, Options<T> {
     /**
-     * The duration for the toast to kept alive before it is removed.
-     * Useful for exit transitions.
+     * The direction of the toast
      */
-    removeDelay: number;
+    dir?: Direction | undefined;
     /**
-     * The document's text/writing direction.
+     * The gap of the toast
      */
-    dir?: Direction | undefined;
+    gap?: number;
+}
+type ToastPropsWithDefault = "type" | "parent" | "duration" | "id";
+type ToastSchema<O = any> = {
+    props: RequiredBy<ToastProps<O>, ToastPropsWithDefault>;
+    context: {
+        mounted: boolean;
+        initialHeight: number;
+        remainingTime: number;
+    };
+    computed: {
+        height: number;
+        heightIndex: number;
+        heightBefore: number;
+        frontmost: boolean;
+        zIndex: number;
+        shouldPersist: boolean;
+    };
+    refs: {
+        closeTimerStartTime: number;
+        lastCloseStartTimerStartTime: number;
+    };
+    state: "visible" | "visible:updating" | "dismissing" | "unmounted" | "visible:persist";
+    tag: "visible" | "paused" | "updating";
+    guard: string;
+    action: string;
+    effect: string;
+    event: EventObject;
+};
+type ToastService = Service<ToastSchema>;
+interface ToastStoreProps {
     /**
-     * The time the toast was created
+     * The placement of the toast
+     * @default "bottom"
      */
-    createdAt: number;
+    placement?: Placement | undefined;
     /**
-     * The time left before the toast is removed
+     * The maximum number of toasts
+     * @default 24
      */
-    remaining: number;
-}
-interface MachinePrivateContext {
-}
-interface MachineState {
-    value: "visible" | "visible:updating" | "dismissing" | "unmounted" | "visible:persist";
-    tags: "visible" | "paused" | "updating";
-}
-type State<T = any> = StateMachine.State<MachineContext<T>, MachineState>;
-type Send = StateMachine.Send;
-type Service<T = any> = Machine<MachineContext<T>, MachineState>;
-interface GroupPublicContext extends DirectionProperty, CommonProperties {
+    max?: number | undefined;
     /**
-     * Whether to pause toast when the user leaves the browser tab
-     * @default false
+     * Whether to overlap the toasts
      */
-    pauseOnPageIdle: boolean;
+    overlap?: boolean | undefined;
     /**
-     * The gap or spacing between toasts
-     * @default 16
+     * The duration of the toast.
+     * By default, it is determined by the type of the toast.
      */
-    gap: number;
+    duration?: number | undefined;
     /**
-     * The maximum number of toasts that can be shown at once
-     * @default Number.MAX_SAFE_INTEGER
+     * The gap between the toasts
+     * @default 16
      */
-    max: number;
+    gap?: number | undefined;
     /**
      * The offset from the safe environment edge of the viewport
      * @default "1rem"
      */
-    offsets: string | Record<"left" | "right" | "bottom" | "top", string>;
+    offsets?: string | Record<"left" | "right" | "bottom" | "top", string> | undefined;
     /**
      * The hotkey that will move focus to the toast group
      * @default '["altKey", "KeyT"]'
      */
-    hotkey: string[];
-    /**
-     * Whether the toasts should overlap each other
-     */
-    overlap?: boolean | undefined;
-    /**
-     * The placement of the toast
-     */
-    placement: Placement;
+    hotkey?: string[] | undefined;
     /**
      * The duration for the toast to kept alive before it is removed.
      * Useful for exit transitions.
      *
      * @default 200
      */
-    removeDelay: number;
+    removeDelay?: number | undefined;
     /**
-     * The duration the toast will be visible
+     * Whether to pause toast when the user leaves the browser tab
+     * @default false
      */
-    duration?: number | undefined;
-}
-interface UserDefinedGroupContext extends RequiredBy<GroupPublicContext, "id"> {
+    pauseOnPageIdle?: boolean | undefined;
 }
-type GroupComputedContext = Readonly<{
+interface ToastGroupProps extends DirectionProperty, CommonProperties {
     /**
-     * @computed
-     * The total number of toasts in the group
+     * The store of the toast
      */
-    count: number;
-}>;
-interface GroupPrivateContext<T> extends GenericOptions<T> {
-}
-interface GroupMachineContext<T = any> extends GroupPublicContext, GroupPrivateContext<T>, GroupComputedContext {
-}
-interface GroupMachineState {
-    value: "stack" | "overlap";
-}
-type GroupState<T = any> = StateMachine.State<GroupMachineContext<T>>;
-type GroupSend = StateMachine.Send;
-type GroupService<T = any> = Machine<GroupMachineContext<T>, GroupMachineState>;
-type MaybeFunction<Value, Args> = Value | ((arg: Args) => Value);
-interface PromiseOptions<V, O = any> {
-    loading: Options<O>;
-    success: MaybeFunction<Options<O>, V>;
-    error: MaybeFunction<Options<O>, Error>;
-    finally?: (() => void | Promise<void>) | undefined;
+    store: ToastStore;
 }
-interface GroupProps {
+type ToastGroupSchema = {
+    state: "stack" | "overlap";
+    props: ToastGroupProps;
+    context: {
+        toasts: RequiredBy<ToastProps, ToastPropsWithDefault>[];
+        heights: ToastHeight[];
+    };
+    computed: {
+        count: number;
+        overlap: boolean;
+        placement: Placement;
+    };
+    refs: {
+        dismissableCleanup?: VoidFunction | undefined;
+        lastFocusedEl: HTMLElement | null;
+        isFocusWithin: boolean;
+    };
+    guard: string;
+    effect: string;
+    action: string;
+    event: EventObject;
+};
+type ToastGroupService = Service<ToastGroupSchema>;
+interface ToastStore<V = any> {
     /**
-     * The placement of the toast region
+     * The attributes of the toast store
      */
-    placement: Placement;
+    attrs: Required<ToastStoreProps>;
     /**
-     * The human-readable label for the toast region
+     * Subscribe to the toast store
      */
-    label?: string | undefined;
-}
-interface GroupMachineApi<T extends PropTypes = PropTypes, O = any> {
+    subscribe: (subscriber: (...args: any[]) => void) => VoidFunction;
     /**
-     * The total number of toasts
+     * Create a new toast with the given options
      */
-    getCount(): number;
+    create: (data: Options<V>) => string;
     /**
-     * The placements of the active toasts
+     * Update an existing toast with new properties
      */
-    getPlacements(): Placement[];
+    update: (id: string, data: Partial<ToastProps<V>>) => string;
     /**
-     * The active toasts by placement
+     * Remove a toast by its ID
      */
-    getToastsByPlacement(placement: Placement): Service<O>[];
+    remove: (id: string) => void;
     /**
-     * Returns whether the toast id is visible
+     * Dismiss a toast by its ID. If no ID is provided, dismisses all toasts
      */
-    isVisible(id: string): boolean;
+    dismiss: (id?: string) => void;
     /**
-     * Function to create a toast.
+     * Create an error toast with the given options
      */
-    create(options: Options<O>): string | undefined;
+    error: (data: Options<V>) => void;
     /**
-     * Function to create or update a toast.
+     * Create a success toast with the given options
      */
-    upsert(options: Options<O>): string | undefined;
+    success: (data: Options<V>) => void;
     /**
-     * Function to update a toast's options by id.
+     * Create an info toast with the given options
      */
-    update(id: string, options: Options<O>): void;
+    info: (data: Options<V>) => void;
     /**
-     * Function to create a success toast.
+     * Create a warning toast with the given options
      */
-    success(options: Options<O>): string | undefined;
+    warning: (data: Options<V>) => void;
     /**
-     * Function to create an error toast.
+     * Create a loading toast with the given options
      */
-    error(options: Options<O>): string | undefined;
+    loading: (data: Options<V>) => void;
     /**
-     * Function to create a loading toast.
+     * Get all currently visible toasts
      */
-    loading(options: Options<O>): string | undefined;
+    getVisibleToasts: () => Partial<ToastProps<V>>[];
     /**
-     * Function to resume a toast by id.
+     * Get the total number of toasts
      */
-    resume(id?: string | undefined): void;
+    getCount: () => number;
     /**
-     * Function to pause a toast by id.
+     * Create a toast that tracks a promise's state
      */
-    pause(id?: string | undefined): void;
+    promise: <T>(promise: Promise<T> | (() => Promise<T>), options: PromiseOptions<T, V>, shared?: Omit<Options<V>, "type">) => {
+        id: string | undefined;
+        unwrap: () => Promise<T>;
+    } | undefined;
     /**
-     * Function to dismiss a toast by id.
-     * If no id is provided, all toasts will be dismissed.
+     * Pause a toast's auto-dismiss timer. If no ID is provided, pauses all toasts
      */
-    dismiss(id?: string | undefined): void;
+    pause: (id?: string) => void;
     /**
-     * Function to dismiss all toasts by placement.
+     * Resume a toast's auto-dismiss timer. If no ID is provided, resumes all toasts
      */
-    dismissByPlacement(placement: Placement): void;
+    resume: (id?: string) => void;
     /**
-     * Function to remove a toast by id.
-     * If no id is provided, all toasts will be removed.
+     * Check if a toast with the given ID is currently visible
      */
-    remove(id?: string | undefined): void;
+    isVisible: (id: string) => boolean;
     /**
-     * Function to create a toast from a promise.
-     * - When the promise resolves, the toast will be updated with the success options.
-     * - When the promise rejects, the toast will be updated with the error options.
+     * Check if a toast with the given ID has been dismissed
      */
-    promise<T>(promise: Promise<T> | (() => Promise<T>), options: PromiseOptions<T, O>, shared?: Partial<Options<O>>): string;
+    isDismissed: (id: string) => boolean;
+}
+type MaybeFunction<Value, Args> = Value | ((arg: Args) => Value);
+interface PromiseOptions<V, O = any> {
+    loading?: Omit<Options<O>, "type">;
+    success?: MaybeFunction<Omit<Options<O>, "type">, V>;
+    error?: MaybeFunction<Omit<Options<O>, "type">, unknown>;
+    finally?: (() => void | Promise<void>) | undefined;
+}
+interface GroupProps {
+    /**
+     * The human-readable label for the toast region
+     */
+    label?: string | undefined;
+}
+interface ToastGroupApi<T extends PropTypes = PropTypes, O = any> {
     /**
-     * Function to subscribe to the toast group.
+     * The total number of toasts
+     */
+    getCount(): number;
+    /**
+     * The toasts
+     */
+    getToasts(): ToastProps[];
+    /**
+     * Subscribe to the toast group
      */
     subscribe(callback: (toasts: Options<O>[]) => void): VoidFunction;
-    getGroupProps(options: GroupProps): T["element"];
+    getGroupProps(options?: GroupProps): T["element"];
 }
-interface MachineApi<T extends PropTypes = PropTypes, O = any> extends GenericOptions<O> {
+interface ToastApi<T extends PropTypes = PropTypes, O = any> {
+    /**
+     * The title of the toast.
+     */
+    title: O;
+    /**
+     * The description of the toast.
+     */
+    description: O;
     /**
      * The type of the toast.
      */
@@ -262,6 +320,10 @@ interface MachineApi<T extends PropTypes = PropTypes, O = any> extends GenericOp
      * Whether the toast is visible.
      */
     visible: boolean;
+    /**
+     * Whether the toast should render a close button
+     */
+    closable: boolean;
     /**
      * Whether the toast is paused.
      */
@@ -287,19 +349,19 @@ interface MachineApi<T extends PropTypes = PropTypes, O = any> extends GenericOp
     getActionTriggerProps(): T["button"];
 }
 
-declare function groupConnect<T extends PropTypes, O = any>(serviceOrState: GroupState<O> | GroupService<O>, send: GroupSend, normalize: NormalizeProps<T>): GroupMachineApi<T, O>;
+declare function groupConnect<T extends PropTypes, O = any>(service: Service<ToastGroupSchema>, normalize: NormalizeProps<T>): ToastGroupApi<T, O>;
 
-declare function groupMachine<T = any>(userContext: UserDefinedGroupContext): _zag_js_core.Machine<GroupMachineContext<T>, GroupMachineState, _zag_js_core.StateMachine.AnyEventObject>;
+declare const anatomy: _zag_js_anatomy.AnatomyInstance<"title" | "description" | "group" | "root" | "actionTrigger" | "closeTrigger">;
 
-declare function createToastMachine<T>(options: Options<T>): _zag_js_core.Machine<MachineContext<T>, MachineState, _zag_js_core.StateMachine.AnyEventObject>;
+declare function connect<T extends PropTypes, O>(service: Service<ToastSchema<O>>, normalize: NormalizeProps<T>): ToastApi<T, O>;
 
-declare const anatomy: _zag_js_anatomy.AnatomyInstance<"group" | "title" | "root" | "description" | "actionTrigger" | "closeTrigger">;
+declare const machine: _zag_js_core.MachineConfig<ToastSchema>;
 
-declare function connect<T extends PropTypes, O>(state: State<O>, send: Send, normalize: NormalizeProps<T>): MachineApi<T, O>;
+declare function createToastStore<V = any>(props: ToastStoreProps): ToastStore<V>;
 
 declare const group: {
     connect: typeof groupConnect;
-    machine: typeof groupMachine;
+    machine: _zag_js_core.MachineConfig<ToastGroupSchema>;
 };
 
-export { type ActionOptions, type MachineApi as Api, type GenericOptions, type GroupMachineApi as GroupApi, type UserDefinedGroupContext as GroupMachineContext, type GroupProps, type GroupService, type GroupState, type MachineContext, type Options, type Placement, type PromiseOptions, type Service, type Status, type StatusChangeDetails, type Type, anatomy, connect, createToastMachine as createMachine, group };
+export { type ActionOptions, type ToastApi as Api, type ToastGroupApi as GroupApi, type ToastGroupProps as GroupProps, type ToastGroupService as GroupService, type Options, type Placement, type PromiseOptions, type ToastProps as Props, type ToastService as Service, type Status, type StatusChangeDetails, type ToastStore as Store, type ToastStoreProps as StoreProps, type Type, anatomy, connect, createToastStore as createStore, group, machine };