@tuwaio/nova-transactions 0.4.2 → 0.4.4

package/dist/{TransactionsInfoModal-EKgcn7Ot.d.cts → TransactionsInfoModal-Cd6hZioh.d.cts}

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ToastCloseButtonProps, DialogContent } from '@tuwaio/nova-core';
 import { TransactionStatus, Transaction, TxAdapter, TransactionPool, TxInMemoryPagination, ITxTrackingStore, InitialTransaction } from '@tuwaio/pulsar-core';
-import { ReactNode, ComponentType, JSX, ComponentPropsWithoutRef } from 'react';
+import { ReactNode, ComponentType, ComponentPropsWithoutRef, JSX } from 'react';
 import { OrbitAdapter, TuwaErrorState } from '@tuwaio/orbit-core';
-import { ToastContainerProps, ToastContentProps } from 'react-toastify';
+import { ToastContentProps, ToastContainerProps } from 'react-toastify';
 import { MotionProps } from 'framer-motion';
 
 /**
@@ -64,6 +64,171 @@ type StatusAwareTextProps = {
  */
 declare function StatusAwareText({ txStatus, source, fallback, variant, className, applyColor, }: StatusAwareTextProps): ReactNode;
 
+/**
+ * @file Contains the `ToastValidationError` component, a top-center error toast
+ * that fires when `executeTxAction` throws **before** the transaction is added
+ * to the pool — e.g., when input metadata fails Pulsar's validation rules or
+ * when a `beforeTxProcess` preflight check rejects.
+ */
+
+/** Props forwarded to a custom icon component inside `ToastValidationError`. */
+type ToastValidationErrorIconProps = {
+    /** Whether the error text has already been copied to the clipboard. */
+    isCopied: boolean;
+    /** Optional additional CSS classes. */
+    className?: string;
+    /** Whether the element is decorative (aria-hidden). */
+    'aria-hidden'?: boolean;
+};
+/** Props forwarded to a custom title component inside `ToastValidationError`. */
+type ToastValidationErrorTitleProps = {
+    /** The resolved title string (from labels or prop override). */
+    title: string;
+    /** Optional additional CSS classes. */
+    className?: string;
+};
+/** Props forwarded to a custom field badge component inside `ToastValidationError`. */
+type ToastValidationErrorFieldProps = {
+    /** The human-readable label prefix (e.g., "Field"). */
+    fieldLabel: string;
+    /** The actual field identifier that failed validation (e.g., "title"). */
+    fieldName: string;
+    /** Optional additional CSS classes. */
+    className?: string;
+};
+/** Props forwarded to a custom message component inside `ToastValidationError`. */
+type ToastValidationErrorMessageProps = {
+    /** The error message string. */
+    message: string;
+    /** Optional additional CSS classes. */
+    className?: string;
+};
+/** Props forwarded to a custom copy-button content component. */
+type ToastValidationErrorCopyContentProps = {
+    /** The icon element to render inside the button. */
+    icon: ReactNode;
+    /** Whether the text has been copied. */
+    isCopied: boolean;
+    /** The label to show before copying. */
+    copyLabel: string;
+    /** The label to show after a successful copy. */
+    copiedLabel: string;
+};
+/**
+ * Granular class name overrides for every sub-element of `ToastValidationError`.
+ * All keys are optional — omit any key to keep the default Tailwind classes.
+ */
+type ToastValidationErrorClassNames = {
+    /** Classes applied to the outermost container `<div>`. */
+    container?: string;
+    /** Classes applied to the header row (icon + title + copy button). */
+    header?: string;
+    /** Classes applied to the title/icon wrapper. */
+    titleWrapper?: string;
+    /** Classes applied to the `<ExclamationTriangleIcon>` (or custom icon). */
+    icon?: string;
+    /** Classes applied to the title text node. */
+    title?: string;
+    /** Classes applied to the field badge pill. */
+    fieldBadge?: string;
+    /** Classes applied to the scrollable message container. */
+    messageContainer?: string;
+    /** Classes applied to the mono message `<p>`. */
+    messageText?: string;
+    /** Classes applied to the copy button. */
+    copyButton?: string;
+};
+/**
+ * Customization options for `ToastValidationError`.
+ *
+ * All keys are optional. Provide only what you want to override — defaults
+ * follow the same visual language as the rest of `nova-transactions`.
+ */
+type ToastValidationErrorCustomization = {
+    /**
+     * Replace any default sub-component with your own.
+     * Each slot receives the same props the default component does,
+     * so you can wrap or fully replace the rendering.
+     */
+    components?: {
+        /** Custom warning icon (top-left of the header). */
+        Icon?: ComponentType<ToastValidationErrorIconProps>;
+        /** Custom title renderer. */
+        Title?: ComponentType<ToastValidationErrorTitleProps>;
+        /** Custom field-badge renderer (shown only when `fieldName` is provided). */
+        FieldBadge?: ComponentType<ToastValidationErrorFieldProps>;
+        /** Custom error message renderer. */
+        Message?: ComponentType<ToastValidationErrorMessageProps>;
+        /** Custom inner content for the copy button (icon + label). */
+        CopyContent?: ComponentType<ToastValidationErrorCopyContentProps>;
+    };
+    /** Override native HTML props on the root container. */
+    containerProps?: Partial<Omit<ComponentPropsWithoutRef<'div'>, 'style'>>;
+    /** Override native HTML props on the copy button. */
+    buttonProps?: Partial<Omit<ComponentPropsWithoutRef<'button'>, 'style'>>;
+    /** Granular Tailwind class overrides for every sub-element. */
+    classNames?: ToastValidationErrorClassNames;
+};
+/**
+ * Props accepted by the `ToastValidationError` component.
+ */
+type ToastValidationErrorProps = {
+    /**
+     * The human-readable error message to display.
+     * Typically `error.message` from the caught `Error`.
+     */
+    message: string;
+    /**
+     * The raw error text that will be written to the clipboard.
+     * Falls back to `message` when not provided.
+     */
+    rawError?: string;
+    /**
+     * The name of the field that triggered the validation failure.
+     * When provided (e.g. `"title"`, `"description"`), a small badge is rendered
+     * below the header so users know exactly which input to fix.
+     * Omit for generic pre-flight errors (`beforeTxProcess` rejections).
+     */
+    fieldName?: string;
+    /** Optional additional CSS class on the outermost container. */
+    className?: string;
+    /**
+     * Injected by `react-toastify` when used as toast content.
+     * Calling it programmatically closes this specific toast instance.
+     */
+    closeToast?: ToastContentProps['closeToast'];
+    /** Full customization override object. */
+    customization?: ToastValidationErrorCustomization;
+};
+/**
+ * `ToastValidationError` is a self-contained toast body for pre-submission errors.
+ *
+ * It is designed to be rendered inside a `react-toastify` `ToastContainer` with
+ * `position="top-center"` and `autoClose={6000}` / `pauseOnHover`. The visual
+ * language mirrors `TxErrorBlock` and `nova-connect`'s `ToastError`:
+ *
+ * - Error color tokens (`--tuwa-error-*`)
+ * - `ExclamationTriangleIcon` header icon
+ * - Optional field badge identifying the offending input
+ * - Scrollable monospace message body
+ * - One-click copy-to-clipboard with feedback
+ *
+ * @example
+ * ```tsx
+ * toast(
+ *   (props) => (
+ *     <ToastValidationError
+ *       {...props}
+ *       message={error.message}
+ *       fieldName={(error as PulsarTransactionValidationError).field}
+ *     />
+ *   ),
+ *   { containerId: 'nova-validation-errors', type: 'error' }
+ * );
+ * ```
+ */
+declare function ToastValidationError({ message, rawError, fieldName, className, customization, }: ToastValidationErrorProps): JSX.Element;
+
 /**
  * @file This file defines the TypeScript type for the library's internationalization (i18n) labels.
  * It provides a strict structure for all text used in the UI components, ensuring type safety for different languages.
@@ -143,6 +308,21 @@ type NovaTransactionsLabels = {
         /** Confirmation text shown after copying an error message. */
         copied: string;
     };
+    /**
+     * Labels for the pre-submission validation error toast.
+     * This toast fires when `executeTxAction` throws before the transaction
+     * is added to the pool (e.g., validation failure, `beforeTxProcess` rejection).
+     */
+    validationError: {
+        /** The main title shown in the toast header. */
+        title: string;
+        /** Prefix label for the field that caused the validation failure, e.g. "Field: title". */
+        field: string;
+        /** Label for the copy-error button before it is clicked. */
+        copy: string;
+        /** Label for the copy-error button after a successful copy. */
+        copied: string;
+    };
     /** Labels for the detailed transaction tracking modal. */
     trackingModal: {
         /** The main title of the tracking modal. */
@@ -269,31 +449,74 @@ type NovaTransactionsLabels = {
 };
 
 /**
- * Defines the props for the NovaTransactionsProvider component.
+ * Defines the props for the `NovaTransactionsProvider` component.
+ *
+ * @template T The specific transaction type, extending the base `Transaction`.
  */
 type NovaTransactionsProviderProps<T extends Transaction> = {
+    /** The chain adapter (or array of adapters) passed through to all child components. */
     adapter: TxAdapter<T> | TxAdapter<T>[];
+    /** The currently connected wallet address, used to gate certain UI actions. */
     connectedWalletAddress?: string;
+    /** The active adapter type, used for chain-specific logic in modals. */
     connectedAdapterType?: OrbitAdapter;
+    /** The live transaction pool from the Pulsar store. */
     transactionsPool: TransactionPool<T>;
+    /** Partial label overrides for i18n. Merged with the built-in English defaults. */
     labels?: Partial<NovaTransactionsLabels>;
+    /**
+     * Feature flags to selectively enable or disable UI sub-systems.
+     * All features are **enabled** by default.
+     */
     features?: {
+        /** Enables bottom-right transaction progress toasts. @defaultValue `true` */
         toasts?: boolean;
+        /** Enables the full-screen transaction history modal. @defaultValue `true` */
         transactionsModal?: boolean;
+        /** Enables the step-by-step tracking modal that opens on submission. @defaultValue `true` */
         trackingTxModal?: boolean;
+        /**
+         * Enables the top-center pre-submission error toast.
+         * This fires when `executeTxAction` throws before the transaction reaches the pool
+         * (validation failures, `beforeTxProcess` rejections, missing adapter, etc.).
+         * @defaultValue `true`
+         */
+        validationErrorToast?: boolean;
     };
+    /** Customization overrides for individual UI sub-systems. */
     customization?: {
+        /** Overrides for the bottom-right transaction progress toast body. */
         toast?: ToastTransactionCustomization<T>;
+        /** Overrides for the close button shared by all transaction toasts. */
         toastCloseButton?: Omit<ToastCloseButtonProps, 'closeToast'>;
+        /** Overrides for the full-screen transaction history modal. */
         transactionsInfoModal?: TransactionsInfoModalCustomization<T>;
+        /** Overrides for the step-by-step tracking modal. */
         trackingTxModal?: TrackingTxModalCustomization<T>;
+        /**
+         * Overrides for the top-center pre-submission validation error toast.
+         * See `ToastValidationErrorCustomization` for available slots.
+         */
+        validationErrorToast?: ToastValidationErrorCustomization;
     };
     /** Pagination state for infinite scroll, forwarded to TransactionsInfoModal and TransactionsHistory. */
     pagination?: TxInMemoryPagination;
 } & Pick<ITxTrackingStore<T>, 'closeTxTrackedModal' | 'executeTxAction' | 'initialTx'> & Omit<ToastContainerProps, 'containerId'>;
 /**
- * The main component for the Nova UI ecosystem. It renders and orchestrates all
- * UI elements like toasts and modals, and provides the i18n context.
+ * The root provider for the Nova UI ecosystem.
+ *
+ * Renders and orchestrates all UI sub-systems:
+ * - **Bottom-right transaction toasts** — live progress updates for every tracked transaction.
+ * - **Top-center validation error toast** — fires when `executeTxAction` throws *before*
+ *   the transaction is added to the pool (e.g., metadata validation failure,
+ *   `beforeTxProcess` rejection, or missing adapter).
+ * - **Transaction history modal** — paginated full-screen history.
+ * - **Tracking modal** — step-by-step view for the most recent transaction.
+ *
+ * Place this component once at the top level of your application, passing the live
+ * Pulsar store state as props.
+ *
+ * @template T The specific transaction type, extending the base `Transaction`.
  */
 declare function NovaTransactionsProvider<T extends Transaction>({ adapter, connectedWalletAddress, connectedAdapterType, transactionsPool, initialTx, executeTxAction, closeTxTrackedModal, labels, features, customization, pagination, ...toastProps }: NovaTransactionsProviderProps<T>): react_jsx_runtime.JSX.Element;
 
@@ -944,4 +1167,4 @@ type TransactionsInfoModalProps<T extends Transaction> = Pick<NovaTransactionsPr
 };
 declare function TransactionsInfoModal<T extends Transaction>({ isOpen, setIsOpen, customization, adapter, connectedWalletAddress, transactionsPool, pagination, selectedTxKey, }: TransactionsInfoModalProps<T>): react_jsx_runtime.JSX.Element;
 
-export { TransactionHistoryItem as A, type TransactionKeyProps as B, type CopyableFieldProps as C, type DetailItemProps as D, TransactionKey as E, type TransactionsHistoryLoaderProps as F, type TransactionsHistoryCustomization as G, type HashLinkProps as H, type TransactionsHistoryProps as I, type JsonBlockProps as J, TransactionsHistory as K, type TransactionsInfoModalCustomization as L, type MetadataRowProps as M, type NovaTransactionsLabels as N, type TransactionsInfoModalProps as O, TransactionsInfoModal as P, type TransactionStatusBadgeProps as Q, TransactionStatusBadge as R, type StatusAwareTextProps as S, type ToastTransactionCustomization as T, type NovaTransactionsProviderProps as U, NovaTransactionsProvider as V, HashLink as a, StatusAwareText as b, type ToastTransactionProps as c, ToastTransaction as d, type TrackingTxModalCustomization as e, type TrackingTxModalProps as f, TrackingTxModal as g, type TxErrorBlockClassNames as h, type TxErrorBlockProps as i, TxErrorBlock as j, type TxInfoBlockCustomization as k, type TxInfoBlockProps as l, TxInfoBlock as m, type StepStatus as n, type StepClassNames as o, type StepProps as p, type TxProgressIndicatorProps as q, TxProgressIndicator as r, type TxStatusVisualClassNames as s, type TxStatusVisualProps as t, TxStatusVisual as u, type TransactionDetailsCustomization as v, type TransactionDetailsProps as w, TransactionDetails as x, type TransactionHistoryItemCustomization as y, type TransactionHistoryItemProps as z };
+export { type TxStatusVisualClassNames as $, type TransactionKeyProps as A, TransactionStatusBadge as B, type CopyableFieldProps as C, type DetailItemProps as D, type TransactionStatusBadgeProps as E, TransactionsHistory as F, type TransactionsHistoryCustomization as G, HashLink as H, type TransactionsHistoryLoaderProps as I, type JsonBlockProps as J, type TransactionsHistoryProps as K, TransactionsInfoModal as L, type MetadataRowProps as M, type NovaTransactionsLabels as N, type TransactionsInfoModalCustomization as O, type TransactionsInfoModalProps as P, TxErrorBlock as Q, type TxErrorBlockClassNames as R, StatusAwareText as S, ToastTransaction as T, type TxErrorBlockProps as U, TxInfoBlock as V, type TxInfoBlockCustomization as W, type TxInfoBlockProps as X, TxProgressIndicator as Y, type TxProgressIndicatorProps as Z, TxStatusVisual as _, type HashLinkProps as a, type TxStatusVisualProps as a0, NovaTransactionsProvider as a1, type NovaTransactionsProviderProps as a2, type StatusAwareTextProps as b, type StepClassNames as c, type StepProps as d, type StepStatus as e, type ToastTransactionCustomization as f, type ToastTransactionProps as g, ToastValidationError as h, type ToastValidationErrorClassNames as i, type ToastValidationErrorCopyContentProps as j, type ToastValidationErrorCustomization as k, type ToastValidationErrorFieldProps as l, type ToastValidationErrorIconProps as m, type ToastValidationErrorMessageProps as n, type ToastValidationErrorProps as o, type ToastValidationErrorTitleProps as p, TrackingTxModal as q, type TrackingTxModalCustomization as r, type TrackingTxModalProps as s, TransactionDetails as t, type TransactionDetailsCustomization as u, type TransactionDetailsProps as v, TransactionHistoryItem as w, type TransactionHistoryItemCustomization as x, type TransactionHistoryItemProps as y, TransactionKey as z };

package/dist/{TransactionsInfoModal-EKgcn7Ot.d.ts → TransactionsInfoModal-Cd6hZioh.d.ts}

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ToastCloseButtonProps, DialogContent } from '@tuwaio/nova-core';
 import { TransactionStatus, Transaction, TxAdapter, TransactionPool, TxInMemoryPagination, ITxTrackingStore, InitialTransaction } from '@tuwaio/pulsar-core';
-import { ReactNode, ComponentType, JSX, ComponentPropsWithoutRef } from 'react';
+import { ReactNode, ComponentType, ComponentPropsWithoutRef, JSX } from 'react';
 import { OrbitAdapter, TuwaErrorState } from '@tuwaio/orbit-core';
-import { ToastContainerProps, ToastContentProps } from 'react-toastify';
+import { ToastContentProps, ToastContainerProps } from 'react-toastify';
 import { MotionProps } from 'framer-motion';
 
 /**
@@ -64,6 +64,171 @@ type StatusAwareTextProps = {
  */
 declare function StatusAwareText({ txStatus, source, fallback, variant, className, applyColor, }: StatusAwareTextProps): ReactNode;
 
+/**
+ * @file Contains the `ToastValidationError` component, a top-center error toast
+ * that fires when `executeTxAction` throws **before** the transaction is added
+ * to the pool — e.g., when input metadata fails Pulsar's validation rules or
+ * when a `beforeTxProcess` preflight check rejects.
+ */
+
+/** Props forwarded to a custom icon component inside `ToastValidationError`. */
+type ToastValidationErrorIconProps = {
+    /** Whether the error text has already been copied to the clipboard. */
+    isCopied: boolean;
+    /** Optional additional CSS classes. */
+    className?: string;
+    /** Whether the element is decorative (aria-hidden). */
+    'aria-hidden'?: boolean;
+};
+/** Props forwarded to a custom title component inside `ToastValidationError`. */
+type ToastValidationErrorTitleProps = {
+    /** The resolved title string (from labels or prop override). */
+    title: string;
+    /** Optional additional CSS classes. */
+    className?: string;
+};
+/** Props forwarded to a custom field badge component inside `ToastValidationError`. */
+type ToastValidationErrorFieldProps = {
+    /** The human-readable label prefix (e.g., "Field"). */
+    fieldLabel: string;
+    /** The actual field identifier that failed validation (e.g., "title"). */
+    fieldName: string;
+    /** Optional additional CSS classes. */
+    className?: string;
+};
+/** Props forwarded to a custom message component inside `ToastValidationError`. */
+type ToastValidationErrorMessageProps = {
+    /** The error message string. */
+    message: string;
+    /** Optional additional CSS classes. */
+    className?: string;
+};
+/** Props forwarded to a custom copy-button content component. */
+type ToastValidationErrorCopyContentProps = {
+    /** The icon element to render inside the button. */
+    icon: ReactNode;
+    /** Whether the text has been copied. */
+    isCopied: boolean;
+    /** The label to show before copying. */
+    copyLabel: string;
+    /** The label to show after a successful copy. */
+    copiedLabel: string;
+};
+/**
+ * Granular class name overrides for every sub-element of `ToastValidationError`.
+ * All keys are optional — omit any key to keep the default Tailwind classes.
+ */
+type ToastValidationErrorClassNames = {
+    /** Classes applied to the outermost container `<div>`. */
+    container?: string;
+    /** Classes applied to the header row (icon + title + copy button). */
+    header?: string;
+    /** Classes applied to the title/icon wrapper. */
+    titleWrapper?: string;
+    /** Classes applied to the `<ExclamationTriangleIcon>` (or custom icon). */
+    icon?: string;
+    /** Classes applied to the title text node. */
+    title?: string;
+    /** Classes applied to the field badge pill. */
+    fieldBadge?: string;
+    /** Classes applied to the scrollable message container. */
+    messageContainer?: string;
+    /** Classes applied to the mono message `<p>`. */
+    messageText?: string;
+    /** Classes applied to the copy button. */
+    copyButton?: string;
+};
+/**
+ * Customization options for `ToastValidationError`.
+ *
+ * All keys are optional. Provide only what you want to override — defaults
+ * follow the same visual language as the rest of `nova-transactions`.
+ */
+type ToastValidationErrorCustomization = {
+    /**
+     * Replace any default sub-component with your own.
+     * Each slot receives the same props the default component does,
+     * so you can wrap or fully replace the rendering.
+     */
+    components?: {
+        /** Custom warning icon (top-left of the header). */
+        Icon?: ComponentType<ToastValidationErrorIconProps>;
+        /** Custom title renderer. */
+        Title?: ComponentType<ToastValidationErrorTitleProps>;
+        /** Custom field-badge renderer (shown only when `fieldName` is provided). */
+        FieldBadge?: ComponentType<ToastValidationErrorFieldProps>;
+        /** Custom error message renderer. */
+        Message?: ComponentType<ToastValidationErrorMessageProps>;
+        /** Custom inner content for the copy button (icon + label). */
+        CopyContent?: ComponentType<ToastValidationErrorCopyContentProps>;
+    };
+    /** Override native HTML props on the root container. */
+    containerProps?: Partial<Omit<ComponentPropsWithoutRef<'div'>, 'style'>>;
+    /** Override native HTML props on the copy button. */
+    buttonProps?: Partial<Omit<ComponentPropsWithoutRef<'button'>, 'style'>>;
+    /** Granular Tailwind class overrides for every sub-element. */
+    classNames?: ToastValidationErrorClassNames;
+};
+/**
+ * Props accepted by the `ToastValidationError` component.
+ */
+type ToastValidationErrorProps = {
+    /**
+     * The human-readable error message to display.
+     * Typically `error.message` from the caught `Error`.
+     */
+    message: string;
+    /**
+     * The raw error text that will be written to the clipboard.
+     * Falls back to `message` when not provided.
+     */
+    rawError?: string;
+    /**
+     * The name of the field that triggered the validation failure.
+     * When provided (e.g. `"title"`, `"description"`), a small badge is rendered
+     * below the header so users know exactly which input to fix.
+     * Omit for generic pre-flight errors (`beforeTxProcess` rejections).
+     */
+    fieldName?: string;
+    /** Optional additional CSS class on the outermost container. */
+    className?: string;
+    /**
+     * Injected by `react-toastify` when used as toast content.
+     * Calling it programmatically closes this specific toast instance.
+     */
+    closeToast?: ToastContentProps['closeToast'];
+    /** Full customization override object. */
+    customization?: ToastValidationErrorCustomization;
+};
+/**
+ * `ToastValidationError` is a self-contained toast body for pre-submission errors.
+ *
+ * It is designed to be rendered inside a `react-toastify` `ToastContainer` with
+ * `position="top-center"` and `autoClose={6000}` / `pauseOnHover`. The visual
+ * language mirrors `TxErrorBlock` and `nova-connect`'s `ToastError`:
+ *
+ * - Error color tokens (`--tuwa-error-*`)
+ * - `ExclamationTriangleIcon` header icon
+ * - Optional field badge identifying the offending input
+ * - Scrollable monospace message body
+ * - One-click copy-to-clipboard with feedback
+ *
+ * @example
+ * ```tsx
+ * toast(
+ *   (props) => (
+ *     <ToastValidationError
+ *       {...props}
+ *       message={error.message}
+ *       fieldName={(error as PulsarTransactionValidationError).field}
+ *     />
+ *   ),
+ *   { containerId: 'nova-validation-errors', type: 'error' }
+ * );
+ * ```
+ */
+declare function ToastValidationError({ message, rawError, fieldName, className, customization, }: ToastValidationErrorProps): JSX.Element;
+
 /**
  * @file This file defines the TypeScript type for the library's internationalization (i18n) labels.
  * It provides a strict structure for all text used in the UI components, ensuring type safety for different languages.
@@ -143,6 +308,21 @@ type NovaTransactionsLabels = {
         /** Confirmation text shown after copying an error message. */
         copied: string;
     };
+    /**
+     * Labels for the pre-submission validation error toast.
+     * This toast fires when `executeTxAction` throws before the transaction
+     * is added to the pool (e.g., validation failure, `beforeTxProcess` rejection).
+     */
+    validationError: {
+        /** The main title shown in the toast header. */
+        title: string;
+        /** Prefix label for the field that caused the validation failure, e.g. "Field: title". */
+        field: string;
+        /** Label for the copy-error button before it is clicked. */
+        copy: string;
+        /** Label for the copy-error button after a successful copy. */
+        copied: string;
+    };
     /** Labels for the detailed transaction tracking modal. */
     trackingModal: {
         /** The main title of the tracking modal. */
@@ -269,31 +449,74 @@ type NovaTransactionsLabels = {
 };
 
 /**
- * Defines the props for the NovaTransactionsProvider component.
+ * Defines the props for the `NovaTransactionsProvider` component.
+ *
+ * @template T The specific transaction type, extending the base `Transaction`.
  */
 type NovaTransactionsProviderProps<T extends Transaction> = {
+    /** The chain adapter (or array of adapters) passed through to all child components. */
     adapter: TxAdapter<T> | TxAdapter<T>[];
+    /** The currently connected wallet address, used to gate certain UI actions. */
     connectedWalletAddress?: string;
+    /** The active adapter type, used for chain-specific logic in modals. */
     connectedAdapterType?: OrbitAdapter;
+    /** The live transaction pool from the Pulsar store. */
     transactionsPool: TransactionPool<T>;
+    /** Partial label overrides for i18n. Merged with the built-in English defaults. */
     labels?: Partial<NovaTransactionsLabels>;
+    /**
+     * Feature flags to selectively enable or disable UI sub-systems.
+     * All features are **enabled** by default.
+     */
     features?: {
+        /** Enables bottom-right transaction progress toasts. @defaultValue `true` */
         toasts?: boolean;
+        /** Enables the full-screen transaction history modal. @defaultValue `true` */
         transactionsModal?: boolean;
+        /** Enables the step-by-step tracking modal that opens on submission. @defaultValue `true` */
         trackingTxModal?: boolean;
+        /**
+         * Enables the top-center pre-submission error toast.
+         * This fires when `executeTxAction` throws before the transaction reaches the pool
+         * (validation failures, `beforeTxProcess` rejections, missing adapter, etc.).
+         * @defaultValue `true`
+         */
+        validationErrorToast?: boolean;
     };
+    /** Customization overrides for individual UI sub-systems. */
     customization?: {
+        /** Overrides for the bottom-right transaction progress toast body. */
         toast?: ToastTransactionCustomization<T>;
+        /** Overrides for the close button shared by all transaction toasts. */
         toastCloseButton?: Omit<ToastCloseButtonProps, 'closeToast'>;
+        /** Overrides for the full-screen transaction history modal. */
         transactionsInfoModal?: TransactionsInfoModalCustomization<T>;
+        /** Overrides for the step-by-step tracking modal. */
         trackingTxModal?: TrackingTxModalCustomization<T>;
+        /**
+         * Overrides for the top-center pre-submission validation error toast.
+         * See `ToastValidationErrorCustomization` for available slots.
+         */
+        validationErrorToast?: ToastValidationErrorCustomization;
     };
     /** Pagination state for infinite scroll, forwarded to TransactionsInfoModal and TransactionsHistory. */
     pagination?: TxInMemoryPagination;
 } & Pick<ITxTrackingStore<T>, 'closeTxTrackedModal' | 'executeTxAction' | 'initialTx'> & Omit<ToastContainerProps, 'containerId'>;
 /**
- * The main component for the Nova UI ecosystem. It renders and orchestrates all
- * UI elements like toasts and modals, and provides the i18n context.
+ * The root provider for the Nova UI ecosystem.
+ *
+ * Renders and orchestrates all UI sub-systems:
+ * - **Bottom-right transaction toasts** — live progress updates for every tracked transaction.
+ * - **Top-center validation error toast** — fires when `executeTxAction` throws *before*
+ *   the transaction is added to the pool (e.g., metadata validation failure,
+ *   `beforeTxProcess` rejection, or missing adapter).
+ * - **Transaction history modal** — paginated full-screen history.
+ * - **Tracking modal** — step-by-step view for the most recent transaction.
+ *
+ * Place this component once at the top level of your application, passing the live
+ * Pulsar store state as props.
+ *
+ * @template T The specific transaction type, extending the base `Transaction`.
  */
 declare function NovaTransactionsProvider<T extends Transaction>({ adapter, connectedWalletAddress, connectedAdapterType, transactionsPool, initialTx, executeTxAction, closeTxTrackedModal, labels, features, customization, pagination, ...toastProps }: NovaTransactionsProviderProps<T>): react_jsx_runtime.JSX.Element;
 
@@ -944,4 +1167,4 @@ type TransactionsInfoModalProps<T extends Transaction> = Pick<NovaTransactionsPr
 };
 declare function TransactionsInfoModal<T extends Transaction>({ isOpen, setIsOpen, customization, adapter, connectedWalletAddress, transactionsPool, pagination, selectedTxKey, }: TransactionsInfoModalProps<T>): react_jsx_runtime.JSX.Element;
 
-export { TransactionHistoryItem as A, type TransactionKeyProps as B, type CopyableFieldProps as C, type DetailItemProps as D, TransactionKey as E, type TransactionsHistoryLoaderProps as F, type TransactionsHistoryCustomization as G, type HashLinkProps as H, type TransactionsHistoryProps as I, type JsonBlockProps as J, TransactionsHistory as K, type TransactionsInfoModalCustomization as L, type MetadataRowProps as M, type NovaTransactionsLabels as N, type TransactionsInfoModalProps as O, TransactionsInfoModal as P, type TransactionStatusBadgeProps as Q, TransactionStatusBadge as R, type StatusAwareTextProps as S, type ToastTransactionCustomization as T, type NovaTransactionsProviderProps as U, NovaTransactionsProvider as V, HashLink as a, StatusAwareText as b, type ToastTransactionProps as c, ToastTransaction as d, type TrackingTxModalCustomization as e, type TrackingTxModalProps as f, TrackingTxModal as g, type TxErrorBlockClassNames as h, type TxErrorBlockProps as i, TxErrorBlock as j, type TxInfoBlockCustomization as k, type TxInfoBlockProps as l, TxInfoBlock as m, type StepStatus as n, type StepClassNames as o, type StepProps as p, type TxProgressIndicatorProps as q, TxProgressIndicator as r, type TxStatusVisualClassNames as s, type TxStatusVisualProps as t, TxStatusVisual as u, type TransactionDetailsCustomization as v, type TransactionDetailsProps as w, TransactionDetails as x, type TransactionHistoryItemCustomization as y, type TransactionHistoryItemProps as z };
+export { type TxStatusVisualClassNames as $, type TransactionKeyProps as A, TransactionStatusBadge as B, type CopyableFieldProps as C, type DetailItemProps as D, type TransactionStatusBadgeProps as E, TransactionsHistory as F, type TransactionsHistoryCustomization as G, HashLink as H, type TransactionsHistoryLoaderProps as I, type JsonBlockProps as J, type TransactionsHistoryProps as K, TransactionsInfoModal as L, type MetadataRowProps as M, type NovaTransactionsLabels as N, type TransactionsInfoModalCustomization as O, type TransactionsInfoModalProps as P, TxErrorBlock as Q, type TxErrorBlockClassNames as R, StatusAwareText as S, ToastTransaction as T, type TxErrorBlockProps as U, TxInfoBlock as V, type TxInfoBlockCustomization as W, type TxInfoBlockProps as X, TxProgressIndicator as Y, type TxProgressIndicatorProps as Z, TxStatusVisual as _, type HashLinkProps as a, type TxStatusVisualProps as a0, NovaTransactionsProvider as a1, type NovaTransactionsProviderProps as a2, type StatusAwareTextProps as b, type StepClassNames as c, type StepProps as d, type StepStatus as e, type ToastTransactionCustomization as f, type ToastTransactionProps as g, ToastValidationError as h, type ToastValidationErrorClassNames as i, type ToastValidationErrorCopyContentProps as j, type ToastValidationErrorCustomization as k, type ToastValidationErrorFieldProps as l, type ToastValidationErrorIconProps as m, type ToastValidationErrorMessageProps as n, type ToastValidationErrorProps as o, type ToastValidationErrorTitleProps as p, TrackingTxModal as q, type TrackingTxModalCustomization as r, type TrackingTxModalProps as s, TransactionDetails as t, type TransactionDetailsCustomization as u, type TransactionDetailsProps as v, TransactionHistoryItem as w, type TransactionHistoryItemCustomization as x, type TransactionHistoryItemProps as y, TransactionKey as z };