@servicetitan/anvil2 1.44.1 → 1.45.0

package/dist/components/Toast/internal/Toast.d.ts

@@ -0,0 +1,106 @@
+import { AlertProps } from '../../Alert';
+import { ButtonProps } from '../../Button';
+import { ProgressBarProps } from '../../ProgressBar';
+type ToastAction = Pick<ButtonProps, "appearance" | "onClick"> & {
+    label: string;
+};
+/**
+ * Props for the Toast component
+ * @extends ComponentPropsWithoutRef<"div">
+ */
+export type ToastProps = {
+    /**
+     * Action buttons to display in the toast
+     */
+    actions?: {
+        primary: ToastAction;
+        secondary?: ToastAction;
+    };
+    /**
+     * CSS class name for the toast container
+     */
+    containerClassName?: string;
+    /**
+     * Duration in milliseconds before auto-dismiss. Set to false to disable auto-dismiss
+     */
+    duration?: number | false;
+    /**
+     * Additional message content to display below the title
+     */
+    message?: string;
+    /**
+     * Callback function called when toast is dismissed, expired, or closed
+     */
+    onDismiss?: () => void;
+    /**
+     * Progress bar value or indeterminate state
+     */
+    progress?: ProgressBarProps["value"] | "indeterminate";
+    /**
+     * CSS class name for the toast element
+     */
+    toastClassName?: string;
+    /**
+     * Unique identifier for the toast
+     */
+    id: string;
+    /**
+     * This is only run when the "x" button is triggered on the toast.
+     * To run a callback when the toast is closed, expired, or dismissed,
+     * use the `onDismiss` parameter instead.
+     */
+    onClose?: AlertProps["onClose"];
+    /**
+     * Visual status of the toast (info, success, warning, danger)
+     */
+    status: AlertProps["status"];
+    /**
+     * Title text displayed in the toast
+     */
+    title: string;
+    /**
+     * Timestamp when the toast was created (internal use)
+     */
+    createdAt?: number;
+    /**
+     * Position index of the toast in the stack (internal use)
+     */
+    index?: number;
+    /**
+     * Whether the toast is below the stack index (internal use)
+     */
+    isBelowStackIndex?: boolean;
+    /**
+     * Whether the toast is currently stacked (internal use)
+     */
+    isStacked?: boolean;
+    /**
+     * Pause status for hover interactions (internal use)
+     */
+    pausedStatus?: number | "resumed";
+};
+/**
+ * Toast component for displaying temporary notifications to users.
+ *
+ * Features:
+ * - Supports different visual styles (info, success, warning, danger)
+ * - Auto-dismiss with configurable duration
+ * - Optional action buttons for user interaction
+ * - Progress bar support for loading states
+ * - Swipe gestures for dismissal
+ * - Stacking behavior for multiple toasts
+ * - Pause on hover functionality
+ * - Accessible with proper ARIA roles
+ * - Smooth animations and transitions
+ *
+ * @example
+ * <Toast
+ *   id="toast-1"
+ *   status="success"
+ *   title="Success!"
+ *   message="Your changes have been saved."
+ *   duration={5000}
+ * />
+ */
+export declare const Toast: import('react').ForwardRefExoticComponent<ToastProps & import('react').RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Toast/internal/ToastProvider.d.ts

@@ -0,0 +1,90 @@
+import { Dispatch, FC, PropsWithChildren, SetStateAction } from 'react';
+import { ToastProps } from './Toast';
+/**
+ * Props for the ToastProvider component
+ * @extends PropsWithChildren
+ */
+export type ToastProviderProps = PropsWithChildren<{
+    /**
+     * Whether this toaster is used within a dialog context
+     * @default false
+     */
+    isDialogToaster?: boolean;
+}>;
+/**
+ * Context properties for the ToastProvider
+ */
+export type ToastProviderContextProps = {
+    /**
+     * Array of active toast notifications
+     */
+    toasts: ToastProps[];
+    /**
+     * Function to update the toast array
+     */
+    setToasts: Dispatch<SetStateAction<ToastProps[]>>;
+    /**
+     * Array of toast height measurements
+     */
+    toastHeights: {
+        id: string;
+        height: number;
+    }[];
+    /**
+     * Function to update toast heights
+     */
+    setToastHeights: Dispatch<SetStateAction<ToastProviderContextProps["toastHeights"]>>;
+    /**
+     * Function to calculate the total height of the toast stack
+     */
+    getToastStackHeight: (index?: number) => number;
+    /**
+     * Number of toasts to display before stacking
+     */
+    toastsBeforeStack: number;
+    /**
+     * Function to update the number of toasts before stacking
+     */
+    setToastsBeforeStack: Dispatch<SetStateAction<number>>;
+    /**
+     * Whether extra toasts are currently visible
+     */
+    extraToastsVisible: boolean;
+    /**
+     * Function to update the visibility of extra toasts
+     */
+    setExtraToastsVisible: Dispatch<SetStateAction<boolean>>;
+    /**
+     * Whether this toaster is used within a dialog context
+     */
+    isDialogToaster: boolean;
+};
+/**
+ * Context for managing toast state and operations
+ */
+export declare const ToastProviderContext: import('react').Context<ToastProviderContextProps>;
+/**
+ * Global reference to toast state setters for external access
+ */
+export declare const getSetToasts: {
+    setToasts: ToastProviderContextProps["setToasts"];
+    setToastHeights: ToastProviderContextProps["setToastHeights"];
+};
+/**
+ * ToastProvider component for managing toast state and context.
+ *
+ * Features:
+ * - Manages toast state and lifecycle
+ * - Handles toast height tracking for positioning
+ * - Provides stacking behavior configuration
+ * - Supports dialog toaster mode
+ * - Automatic duplicate toast detection and removal
+ * - Context-based state management
+ * - Height calculation utilities for positioning
+ *
+ * @example
+ * <ToastProvider isDialogToaster={false}>
+ *   <Toaster id="main-toaster" />
+ * </ToastProvider>
+ */
+export declare const ToastProvider: FC<ToastProviderProps>;

package/dist/components/Toast/internal/ToastStack.d.ts

@@ -0,0 +1,81 @@
+import { ComponentPropsWithoutRef } from 'react';
+import { ToastProps } from './Toast';
+/**
+ * Props for the ToastStack component
+ * @extends ComponentPropsWithoutRef<"div">
+ */
+export type ToastStackProps = Omit<ComponentPropsWithoutRef<"div">, "children"> & {
+    /**
+     * Duration of the toast in milliseconds. If set to `false`, the toast will not auto-dismiss.
+     * If `actions` are provided in the toast method, this prop will be ignored and treated as `false`.
+     * @default false
+     */
+    duration?: number | false;
+    /**
+     * How a screen-reader will announce the hotkey used to set focus on the first toast.
+     * @default "t"
+     */
+    focusKey?: string;
+    /**
+     * How many toasts to display before they start stacking.
+     * @default 3
+     */
+    toastsBeforeStack?: number;
+    /**
+     * The toasts to display in the stack.
+     * @default []
+     */
+    toasts: ToastProps[];
+};
+/**
+ * ToastStack component for displaying a stack of toast notifications.
+ *
+ * Features:
+ * - Displays multiple toasts in a vertical stack
+ * - Automatic stacking behavior when toast count exceeds limit
+ * - Show more button to expand stacked toasts
+ * - Keyboard navigation with hotkey support
+ * - Hover pause functionality for toast timers
+ * - Smooth animations and transitions
+ * - Accessibility features with screen reader support
+ * - Responsive design with mobile touch support
+ * - Focus management for keyboard users
+ *
+ * @example
+ * <ToastStack
+ *   toasts={toastList}
+ *   duration={5000}
+ *   toastsBeforeStack={3}
+ *   focusKey="t"
+ * />
+ *
+ * @example
+ * <ToastStack
+ *   toasts={[toast1, toast2]}
+ *   duration={false}
+ *   toastsBeforeStack={5}
+ * />
+ */
+export declare const ToastStack: import('react').ForwardRefExoticComponent<Omit<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children"> & {
+    /**
+     * Duration of the toast in milliseconds. If set to `false`, the toast will not auto-dismiss.
+     * If `actions` are provided in the toast method, this prop will be ignored and treated as `false`.
+     * @default false
+     */
+    duration?: number | false;
+    /**
+     * How a screen-reader will announce the hotkey used to set focus on the first toast.
+     * @default "t"
+     */
+    focusKey?: string;
+    /**
+     * How many toasts to display before they start stacking.
+     * @default 3
+     */
+    toastsBeforeStack?: number;
+    /**
+     * The toasts to display in the stack.
+     * @default []
+     */
+    toasts: ToastProps[];
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/Toast/internal/Toaster.d.ts

@@ -0,0 +1,108 @@
+import { ComponentPropsWithoutRef } from 'react';
+import { ToastUpdateProps } from './types';
+import { ToastProps } from './Toast';
+import { ToastStackProps } from './ToastStack';
+export type ToastEventType = {
+    eventType: "add" | "update" | "dismiss" | "dismiss-all";
+    toastCount: number;
+    id?: string;
+    toasterId?: string;
+    toastProps?: ToastProps | ToastUpdateProps;
+};
+/**
+ * Props for the Toaster component
+ * @extends ComponentPropsWithoutRef<"div">
+ * @extends Omit<ToastStackProps, "toasts">
+ */
+export type ToasterProps = ComponentPropsWithoutRef<"div"> & Omit<ToastStackProps, "toasts"> & {
+    /**
+     * When `true`, the toaster will not listen for custom events to add, update, or dismiss toasts.
+     * Use this to prevent multiple toasters from displaying the same toasts.
+     * @default false
+     */
+    disableEvents?: boolean;
+    /**
+     * @deprecated This prop has no effect. The toaster no longer conditionally renders internally.
+     * @default false
+     */
+    forceRender?: boolean;
+    /**
+     * Unique toaster id.
+     */
+    id: string;
+    /**
+     * Callback function that is called when toasts are added, updated, or dismissed.
+     */
+    onToastEvent?: (toastEvent: ToastEventType) => void;
+};
+/**
+ * Toaster component for managing and displaying toast notifications.
+ *
+ * Features:
+ * - Manages multiple toast notifications in a stack
+ * - Handles toast positioning and stacking behavior
+ * - Supports custom events for toast management
+ * - Automatic toast dismissal with configurable duration
+ * - Keyboard navigation and accessibility support
+ * - Dialog-aware positioning for modal contexts
+ * - Session storage for dialog toaster state
+ * - Custom event system for toast lifecycle management
+ * - Responsive design with mobile support
+ *
+ * @example
+ * <Toaster
+ *   id="main-toaster"
+ *   duration={5000}
+ *   toastsBeforeStack={3}
+ *   onToastEvent={(event) => console.log('Toast event:', event)}
+ * />
+ *
+ * @example
+ * <Toaster
+ *   id="dialog-toaster"
+ *   disableEvents={false}
+ *   focusKey="t"
+ * />
+ */
+export declare const ToasterContent: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & Omit<ToastStackProps, "toasts"> & {
+    /**
+     * When `true`, the toaster will not listen for custom events to add, update, or dismiss toasts.
+     * Use this to prevent multiple toasters from displaying the same toasts.
+     * @default false
+     */
+    disableEvents?: boolean;
+    /**
+     * @deprecated This prop has no effect. The toaster no longer conditionally renders internally.
+     * @default false
+     */
+    forceRender?: boolean;
+    /**
+     * Unique toaster id.
+     */
+    id: string;
+    /**
+     * Callback function that is called when toasts are added, updated, or dismissed.
+     */
+    onToastEvent?: (toastEvent: ToastEventType) => void;
+} & import('react').RefAttributes<HTMLDivElement>>;
+export declare const Toaster: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & Omit<ToastStackProps, "toasts"> & {
+    /**
+     * When `true`, the toaster will not listen for custom events to add, update, or dismiss toasts.
+     * Use this to prevent multiple toasters from displaying the same toasts.
+     * @default false
+     */
+    disableEvents?: boolean;
+    /**
+     * @deprecated This prop has no effect. The toaster no longer conditionally renders internally.
+     * @default false
+     */
+    forceRender?: boolean;
+    /**
+     * Unique toaster id.
+     */
+    id: string;
+    /**
+     * Callback function that is called when toasts are added, updated, or dismissed.
+     */
+    onToastEvent?: (toastEvent: ToastEventType) => void;
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/Toast/internal/ToasterPopover.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ToasterPopover component for displaying toast notifications in a popover.
+ *
+ * Features:
+ * - Displays toast notifications in a native popover element
+ * - Automatically shows/hides based on toast count
+ * - Handles dialog toaster state management
+ * - Browser compatibility checking for popover support
+ * - Smooth transitions between show/hide states
+ * - Integration with toast provider context
+ *
+ * @example
+ * <ToasterPopover>
+ *   <ToastStack toasts={toastList} />
+ * </ToasterPopover>
+ */
+export declare const ToasterPopover: import('react').ForwardRefExoticComponent<{
+    children?: import('react').ReactNode | undefined;
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/Toast/internal/addOrUpdateToastHeight.d.ts

@@ -0,0 +1,8 @@
+import { ToastProviderContextProps } from './ToastProvider';
+/**
+ * Adds or updates the height of a toast in the height tracking system
+ * @param toastId - The unique identifier of the toast
+ * @param toastHeight - The height of the toast in pixels
+ * @param setToastHeights - Function to update toast heights
+ */
+export declare const addOrUpdateToastHeight: (toastId: string, toastHeight: number, setToastHeights: ToastProviderContextProps["setToastHeights"]) => void;

package/dist/components/Toast/internal/constants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Animation duration for toast transitions in milliseconds
+ */
+export declare const ANIMATION_DURATION = 300;

package/dist/components/Toast/internal/types.d.ts

@@ -0,0 +1,18 @@
+import { ToastProps } from './Toast';
+import { toastProps } from '../toast';
+export type ToastUpdateProps = Partial<toastProps> & {
+    id: string;
+    status?: ToastProps["status"];
+};
+export type ToastCustomEventDetailAdd = ToastProps & {
+    eventType: "add";
+    toasterId?: string;
+};
+export type ToastCustomEventDetailUpdate = ToastUpdateProps & {
+    eventType: "update";
+};
+export type ToastCustomEventDetailDismiss = {
+    id?: string;
+    eventType: "dismiss";
+};
+export type ToastCustomEventDetail = ToastCustomEventDetailAdd | ToastCustomEventDetailUpdate | ToastCustomEventDetailDismiss;

package/dist/components/Toast/internal/useCloseToast.d.ts

@@ -0,0 +1,7 @@
+import { ToastProps } from './Toast';
+/**
+ * Hook that returns a function to close toasts
+ * @param closingToastClassName - CSS class for closing animation
+ * @returns Function to close toasts by ID or all toasts
+ */
+export declare const useCloseToast: (closingToastClassName: ToastProps["toastClassName"]) => (id?: string) => void;

package/dist/components/Toast/internal/useHotkeyFocus.d.ts

@@ -0,0 +1,25 @@
+import { MutableRefObject } from 'react';
+type HotkeyFocusParams = {
+    disabled: boolean;
+    hotkey: string;
+    onHotkeyIn?: () => void | Promise<void>;
+    onHotkeyOut?: () => void | Promise<void>;
+    refToFocus: MutableRefObject<HTMLElement>;
+    rootRef: MutableRefObject<HTMLElement>;
+};
+/**
+ * A hook that listens for a hotkey press and focuses an element when the hotkey is pressed.
+ * The hook also listens for the Escape key to blur the element and refocus the previous element.
+ *
+ * @param params
+ * @param params.disabled - If true, the hotkey will not be active
+ * @param params.hotkey - The key to press to focus the element
+ * @param params.onHotkeyIn - A function to run when the hotkey is pressed; this runs before the element is focused
+ * @param params.onHotkeyOut - A function to run when the user presses Escape after focusing the element
+ * @param params.refToFocus - The ref to the element that will be focused when the hotkey is pressed
+ * @param params.rootRef - The ref to the element that will listen for changes to focus, disabling the Escape key
+ */
+export declare const useHotkeyFocus: ({ disabled, hotkey, onHotkeyIn, onHotkeyOut, refToFocus, rootRef, }: HotkeyFocusParams) => {
+    returnFocusRef: MutableRefObject<HTMLElement | null>;
+};
+export {};

package/dist/components/Toast/internal/useShowMoreButtonPositionStyles.d.ts

@@ -0,0 +1,6 @@
+import { CSSProperties } from 'react';
+/**
+ * Hook for calculating position styles for the show more button
+ * @returns CSS properties for positioning the show more button
+ */
+export declare const useShowMoreButtonPositionStyles: () => CSSProperties;

package/dist/components/Toast/internal/useToastPositionStyles.d.ts

@@ -0,0 +1,7 @@
+import { CSSProperties } from 'react';
+/**
+ * Hook for calculating position styles for individual toasts
+ * @param index - The index of the toast in the stack
+ * @returns CSS properties for positioning the toast
+ */
+export declare const useToastPositionStyles: (index: number) => CSSProperties | undefined;

package/dist/components/Toast/internal/useToasts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hook for accessing toast context and state management functions
+ * @returns ToastProviderContextProps - The toast context with state and functions
+ * @throws Error when used outside of ToastProvider
+ */
+export declare const useToasts: () => import('./ToastProvider').ToastProviderContextProps;

package/dist/components/Toast/toast.d.ts

@@ -1,47 +1,122 @@
-import { toastProps as coreToastProps } from '@servicetitan/hammer-react';
+import { ToastUpdateProps } from './internal/types';
+import { ToastProps } from './internal/Toast';
+export type toastProps = Pick<ToastProps, "actions" | "containerClassName" | "duration" | "message" | "onClose" | "onDismiss" | "progress" | "title" | "toastClassName">;
 /**
- * Props for creating toast notifications
- * @property {string} id - Unique identifier for the toast
- * @property {AlertProps["status"]} status - Visual status of the toast (info, success, warning, danger)
- * @property {string} title - Title text displayed in the toast
- * @property {string} [message] - Additional message content to display below the title
- * @property {number | false} [duration] - Duration in milliseconds before auto-dismiss. Set to false to disable auto-dismiss
- * @property {ToastAction & { secondary?: ToastAction }} [actions] - Action buttons to display in the toast
- * @property {ProgressBarProps["value"] | "indeterminate"} [progress] - Progress bar value or indeterminate state
- * @property {() => void} [onDismiss] - Callback function called when toast is dismissed, expired, or closed
- * @property {() => void} [onClose] - Callback function called only when the close button is clicked
- * @property {string} [toasterId] - ID of the specific toaster to display the toast in
- */
-export type toastProps = coreToastProps;
-/**
- * Toast utility functions for creating and managing toast notifications.
- *
- * Features:
- * - Create toast notifications with various status types
- * - Update existing toasts with new content
- * - Dismiss individual toasts or all toasts
- * - Support for action buttons and progress bars
- * - Automatic tracking ID generation for analytics
- * - Integration with anvil2 toaster system
+ * Use to run toast methods for adding, updating, and dismissing toasts.
  *
- * @example
- * toast.success({
- *   id: "success-toast",
- *   title: "Success!",
- *   message: "Your changes have been saved."
- * });
+ * @method info
+ * @method success
+ * @method warning
+ * @method danger
+ * @method promise
+ * @method update
+ * @method dismiss
  */
 export declare const toast: {
     (): void;
-    info: (props: coreToastProps) => string;
-    success: (props: coreToastProps) => string;
-    warning: (props: coreToastProps) => string;
-    danger: (props: coreToastProps) => string;
-    update: (id: string, props: Omit<import('@servicetitan/hammer-react/dist/components/Toast/toast-methods').ToastUpdateProps, "id">) => void;
+    /**
+     * Use to add info toast to the stack.
+     *
+     * @example
+     * import { toast } from "@servicetitan/anvil2";
+     * const id = toast.info({
+     *   message: "This is an info toast",
+     *   title: "Info",
+     * });
+     */
+    info: (props: toastProps) => string;
+    /**
+     * Use to add success toast to the stack.
+     *
+     * @example
+     * import { toast } from "@servicetitan/anvil2";
+     * const id = toast.success({
+     *   message: "This is an info toast",
+     *   title: "Info",
+     * });
+     */
+    success: (props: toastProps) => string;
+    /**
+     * Use to add warning toast to the stack.
+     *
+     * @example
+     * import { toast } from "@servicetitan/anvil2";
+     * const id = toast.warning({
+     *   message: "This is an info toast",
+     *   title: "Info",
+     * });
+     */
+    warning: (props: toastProps) => string;
+    /**
+     * Use to add danger toast to the stack.
+     *
+     * @example
+     * import { toast } from "@servicetitan/anvil2";
+     * const id = toast.danger({
+     *   message: "This is an info toast",
+     *   title: "Info",
+     * });
+     */
+    danger: (props: toastProps) => string;
+    /**
+     * Use to update a specific toast in the stack.
+     *
+     * @example
+     * import { toast } from "@servicetitan/anvil2";
+     * const id = toast.info({
+     *   message: "This is an info toast",
+     *   title: "Info",
+     * });
+     * toast.update(id, {
+     *   message: "This is an updated toast",
+     *   title: "Updated",
+     * });
+     */
+    update: (id: string, props: Omit<ToastUpdateProps, "id">) => void;
+    /**
+     * Use to dismiss a specific toast in the stack.
+     *
+     * @example
+     * import { toast } from "@servicetitan/anvil2";
+     * const id = toast.info({
+     *   message: "This is an info toast",
+     *   title: "Info",
+     * });
+     * toast.dismiss(id);
+     */
     dismiss: (id?: string) => void;
+    /**
+     * Use to create a toast that updates itself based on a Promise state.
+     *
+     * @example
+     * ```ts
+     * import { toast } from "@servicetitan/anvil2";
+     * toast.promise(
+     *   new Promise((resolve, reject) => {
+     *     setTimeout(() => {
+     *       resolve("This is a success toast");
+     *     }, 2000);
+     *   }),
+     *   {
+     *     loading: {
+     *       message: "This is a loading toast",
+     *       title: "Loading",
+     *     },
+     *     success: (data) => ({
+     *       message: data,
+     *       title: "Success",
+     *     }),
+     *     error: (error) => ({
+     *       message: error,
+     *       title: "Error",
+     *     }),
+     *   },
+     * );
+     * ```
+     */
     promise: (promise: Promise<string>, toastConfig: {
-        loading: coreToastProps;
-        success: (data: string) => Omit<coreToastProps, "id">;
-        error: (error: string) => Omit<coreToastProps, "id">;
+        loading: toastProps;
+        success: (data: string) => Omit<toastProps, "id">;
+        error: (error: string) => Omit<toastProps, "id">;
     }) => Promise<string>;
 };