@lifi/widget 4.0.0-beta.9 → 4.1.0

package/src/types/widget.ts

@@ -5,7 +5,7 @@ import type {
   ExecutionOptions,
   ExtendedChain,
   Order,
-  RouteExtended,
+  Route,
   RouteOptions,
   SDKConfig,
   StaticToken,
@@ -24,7 +24,6 @@ import type {
 import type { TypographyVariantsOptions } from '@mui/material/styles'
 import type {
   CSSProperties,
-  FC,
   PropsWithChildren,
   ReactNode,
   RefObject,
@@ -36,26 +35,45 @@ import type {
 import type { DefaultFieldValues } from '../stores/form/types.js'
 
 export type WidgetVariant = 'compact' | 'wide' | 'drawer'
-export type WidgetSubvariant = 'default' | 'split' | 'custom' | 'refuel'
-export type SplitSubvariant = 'bridge' | 'swap'
-export type SplitSubvariantOptions = {
-  defaultTab: SplitSubvariant
-}
-export type CustomSubvariant = 'checkout' | 'deposit'
-export type WideSubvariant = {
-  disableChainSidebar?: boolean
+
+/** @internal Not part of the public API. */
+export type InternalWidgetMode = 'limit'
+export type WidgetMode =
+  | 'default'
+  | 'split'
+  | 'custom'
+  | 'refuel'
+  | InternalWidgetMode
+export type SplitMode = 'bridge' | 'swap'
+export type SplitModeOptions = {
+  defaultTab: SplitMode
 }
-export interface SubvariantOptions {
+export type CustomMode = 'checkout' | 'deposit'
+export interface ModeOptions {
   /**
-   * Configure split subvariant behavior:
+   * Configure split mode behavior:
    * - 'bridge' | 'swap': Single mode without tabs
    * - { defaultTab: 'bridge' | 'swap' }: Tabs mode with configurable default tab
    */
-  split?: SplitSubvariant | SplitSubvariantOptions
-  custom?: CustomSubvariant
-  wide?: WideSubvariant
+  split?: SplitMode | SplitModeOptions
+  custom?: { type: CustomMode }
 }
 
+/**
+ * Identity of a header navigation tab. Each key maps to a widget variant, mode and
+ * (optionally) mode options; labels are resolved from the key.
+ */
+export type SplitNavigationTabKey = SplitMode
+/** @internal Not part of the public API. */
+export type InternalNavigationTabKey =
+  | 'default'
+  | 'private'
+  | 'refuel'
+  | 'swap-advanced'
+  | 'bridge-advanced'
+  | 'limit'
+export type NavigationTabKey = InternalNavigationTabKey | SplitNavigationTabKey
+
 export type Appearance = PaletteMode | 'system'
 export interface NavigationProps {
   /**
@@ -71,6 +89,7 @@ export type WidgetThemeComponents = Partial<
     | 'MuiAvatar'
     | 'MuiButton'
     | 'MuiCard'
+    | 'MuiDrawer'
     | 'MuiIconButton'
     | 'MuiInputCard'
     | 'MuiNavigationTabs'
@@ -81,10 +100,6 @@ export type WidgetThemeComponents = Partial<
 >
 
 export type WidgetTheme = {
-  /**
-   * @deprecated Use `colorScheme` instead.
-   */
-  palette?: PaletteOptions
   colorSchemes?: {
     light?: {
       palette: PaletteOptions
@@ -103,46 +118,57 @@ export type WidgetTheme = {
   navigation?: NavigationProps
 }
 
-export enum DisabledUI {
-  FromAmount = 'fromAmount',
-  FromToken = 'fromToken',
-  ToAddress = 'toAddress',
-  ToToken = 'toToken',
+export interface DisabledUIConfig {
+  fromAmount?: boolean
+  fromToken?: boolean
+  toAddress?: boolean
+  toToken?: boolean
 }
-export type DisabledUIType = `${DisabledUI}`
-
-export enum HiddenUI {
-  Appearance = 'appearance',
-  DrawerCloseButton = 'drawerCloseButton',
-  History = 'history',
-  Language = 'language',
-  PoweredBy = 'poweredBy',
-  ToAddress = 'toAddress',
-  FromToken = 'fromToken',
-  ToToken = 'toToken',
-  WalletMenu = 'walletMenu',
-  IntegratorStepDetails = 'integratorStepDetails',
-  ReverseTokensButton = 'reverseTokensButton',
-  RouteTokenDescription = 'routeTokenDescription',
-  RouteCardPriceImpact = 'routeCardPriceImpact',
-  ChainSelect = 'chainSelect',
-  BridgesSettings = 'bridgesSettings',
-  AddressBookConnectedWallets = 'addressBookConnectedWallets',
-  LowAddressActivityConfirmation = 'lowAddressActivityConfirmation',
-  GasRefuelMessage = 'gasRefuelMessage',
-  SearchTokenInput = 'searchTokenInput',
-  InsufficientGasMessage = 'insufficientGasMessage',
-  ContactSupport = 'contactSupport',
-  HideSmallBalances = 'hideSmallBalances',
-  AllNetworks = 'allNetworks',
+
+export interface HiddenUIConfig {
+  addressBookConnectedWallets?: boolean
+  allNetworks?: boolean
+  appearance?: boolean
+  bridgesSettings?: boolean
+  chainSelect?: boolean
+  /**
+   * Hide the chain sidebar in the `wide` variant. No effect in other variants.
+   * @default false
+   */
+  chainSidebar?: boolean
+  contactSupport?: boolean
+  /**
+   * Hide the drawer close button. Only meaningful when `variant === 'drawer'`.
+   * @default false
+   */
+  drawerCloseButton?: boolean
+  fromToken?: boolean
+  gasRefuelMessage?: boolean
+  hideSmallBalances?: boolean
+  history?: boolean
+  insufficientGasMessage?: boolean
+  integratorStepDetails?: boolean
+  language?: boolean
+  /**
+   * Hide the warning shown when sending to an address with low historical
+   * on-chain activity (low transaction count or contract-like behavior).
+   * @default false
+   */
+  lowAddressActivityConfirmation?: boolean
+  poweredBy?: boolean
+  reverseTokensButton?: boolean
+  routeCardPriceImpact?: boolean
+  routeTokenDescription?: boolean
+  searchTokenInput?: boolean
+  toAddress?: boolean
+  toToken?: boolean
+  walletMenu?: boolean
 }
-export type HiddenUIType = `${HiddenUI}`
 
-export enum RequiredUI {
-  ToAddress = 'toAddress',
-  AccountDeployedMessage = 'accountDeployedMessage',
+export interface RequiredUIConfig {
+  accountDeployedMessage?: boolean
+  toAddress?: boolean
 }
-export type RequiredUIType = `${RequiredUI}`
 
 export type DefaultUI = {
   transactionDetailsExpanded?: boolean
@@ -174,10 +200,14 @@ export interface WidgetSDKConfig
     | 'apiKey'
     | 'disableVersionCheck'
     | 'integrator'
+    | 'providers'
     | 'routeOptions'
     | 'widgetVersion'
   > {
-  routeOptions?: Omit<RouteOptions, 'bridges' | 'exchanges'>
+  routeOptions?: Omit<
+    RouteOptions,
+    'bridges' | 'exchanges' | 'fee' | 'referrer' | 'order' | 'slippage'
+  >
   executionOptions?: Pick<ExecutionOptions, 'updateTransactionRequestHook'>
 }
 
@@ -225,10 +255,6 @@ export interface WidgetFeeConfig {
    * @returns A promise that resolves to the calculated fee as a number (e.g., 0.03 represents a 3% fee)
    */
   calculateFee?(params: CalculateFeeParams): Promise<number | undefined>
-  /**
-   * @internal
-   */
-  _vcComponent?: FC<{ route: RouteExtended }>
 }
 
 export interface ToAddress {
@@ -289,6 +315,14 @@ export interface RouteLabelRule {
   toChainId?: number[]
   fromTokenAddress?: string[]
   toTokenAddress?: string[]
+  /**
+   * Custom match function evaluated against the route. When provided, its
+   * result is AND'd with the other matching criteria — all specified
+   * conditions must pass for the label to apply. Use this for matching logic
+   * that the built-in fields cannot express (gas costs, step count, route
+   * tags, etc.).
+   */
+  match?: (route: Route) => boolean
 }
 
 export type ExplorerUrl =
@@ -324,7 +358,6 @@ export interface WidgetConfig {
   contractTool?: WidgetContractTool
   integrator: string
   apiKey?: string
-  fee?: number
   feeConfig?: WidgetFeeConfig
   referrer?: string
 
@@ -332,17 +365,30 @@ export interface WidgetConfig {
   slippage?: number
 
   variant?: WidgetVariant
-  subvariant?: WidgetSubvariant
-  subvariantOptions?: SubvariantOptions
+  mode?: WidgetMode
+  modeOptions?: ModeOptions
+  /**
+   * Header navigation tabs, in order. When set, the widget renders a tab bar
+   * and the active tab drives the displayed flow. Each entry is a tab key.
+   *
+   * @internal Not part of the public API.
+   */
+  _navigationTabs?: NavigationTabKey[]
 
   appearance?: Appearance
   theme?: WidgetTheme
 
-  disabledUI?: DisabledUIType[]
-  hiddenUI?: HiddenUIType[]
-  requiredUI?: RequiredUIType[]
+  disabledUI?: DisabledUIConfig
+  hiddenUI?: HiddenUIConfig
+  requiredUI?: RequiredUIConfig
   defaultUI?: DefaultUI
-  useRecommendedRoute?: boolean
+  /**
+   * When true, shows only the recommended route and hides the route
+   * selector UI. Distinct from `routePriority`, which sets the SDK
+   * ranking order across multiple displayed routes.
+   * @default false
+   */
+  showSingleRoute?: boolean
   useRelayerRoutes?: boolean
 
   walletConfig?: WidgetWalletConfig

package/src/utils/compactNumberFormatter.ts

@@ -26,7 +26,7 @@ function toSubscript(n: number): string {
 export const compactNumberFormatter = (
   lng: string | undefined,
   options: any
-) => {
+): ((value: any) => string) => {
   const formatter = new Intl.NumberFormat(lng, {
     notation: 'standard',
     roundingPriority: 'morePrecision',

package/src/utils/converters.ts

@@ -66,7 +66,7 @@ const buildActionsFromTxHistory = (tx: FullStatusData): ExecutionAction[] => {
 export const buildRouteFromTxHistory = (
   tx: FullStatusData,
   tools?: ToolsResponse
-) => {
+): RouteExecution | undefined => {
   const sending = tx.sending as ExtendedTransactionInfo
   const receiving = tx.receiving as ExtendedTransactionInfo
 
@@ -203,7 +203,9 @@ export const buildRouteFromTxHistory = (
           integrator: tx.metadata?.integrator ?? '',
           execution: {
             status: 'DONE', // can be FAILED
-            startedAt: sending.timestamp ?? Date.now(),
+            startedAt: sending.timestamp
+              ? sending.timestamp * 1000
+              : Date.now(),
             actions: buildActionsFromTxHistory(tx),
             fromAmount: sending.amount,
             toAmount: receiving.amount,

package/src/utils/currencyExtendedFormatter.ts

@@ -1,7 +1,7 @@
 export const currencyExtendedFormatter = (
   lng: string | undefined,
   options: any
-) => {
+): ((value: any) => string) => {
   const formatter = new Intl.NumberFormat(lng, {
     ...options,
     style: 'currency',

package/src/utils/deepEqual.ts

@@ -1,6 +1,6 @@
 /** Forked from https://github.com/epoberezkin/fast-deep-equal */
 
-export function deepEqual(a: any, b: any) {
+export function deepEqual(a: any, b: any): boolean {
   if (a === b) {
     return true
   }

package/src/utils/deepMerge.ts

@@ -1,6 +1,6 @@
-const isObject = (obj: any) => obj && typeof obj === 'object'
+const isObject = (obj: any): boolean => obj && typeof obj === 'object'
 
-export const deepMerge = (...objects: any[]) => {
+export const deepMerge = (...objects: any[]): any => {
   return objects.reduce((prev, obj) => {
     for (const key in obj) {
       if (isObject(prev[key]) && isObject(obj[key])) {

package/src/utils/elements.ts

@@ -5,26 +5,28 @@ export enum ElementId {
   ScrollableContainer = 'widget-scrollable-container',
 }
 
-export const createElementId = (ElementId: ElementId, elementId: string) =>
-  elementId ? `${ElementId}-${elementId}` : ElementId
+export const createElementId = (
+  ElementId: ElementId,
+  elementId: string
+): string => (elementId ? `${ElementId}-${elementId}` : ElementId)
 
 // NOTE: The getter functions here are often used with code that can be effected by css changes in the
 //   AppExpandedContainer, RelativeContainer and CssBaselineContainer components as defined in AppContainer.ts
 
-export const getAppContainer = (elementId: string) =>
+export const getAppContainer = (elementId: string): HTMLElement | null =>
   document.getElementById(
     createElementId(ElementId.AppExpandedContainer, elementId)
   )
 
-export const getRelativeContainer = (elementId: string) =>
+export const getRelativeContainer = (elementId: string): HTMLElement | null =>
   document.getElementById(
     createElementId(ElementId.RelativeContainer, elementId)
   )
 
-export const getScrollableContainer = (elementId: string) =>
+export const getScrollableContainer = (elementId: string): HTMLElement | null =>
   document.getElementById(
     createElementId(ElementId.ScrollableContainer, elementId)
   )
 
-export const getHeaderElement = (elementId: string) =>
+export const getHeaderElement = (elementId: string): HTMLElement | null =>
   document.getElementById(createElementId(ElementId.Header, elementId))

package/src/utils/enum.ts

@@ -1,2 +1,4 @@
-export const hasEnumFlag = <T extends number | bigint>(flags: T, flag: T) =>
-  (flags & flag) === flag
+export const hasEnumFlag = <T extends number | bigint>(
+  flags: T,
+  flag: T
+): boolean => (flags & flag) === flag

package/src/utils/fees.ts

@@ -9,8 +9,14 @@ export interface FeesBreakdown {
 
 export const getAccumulatedFeeCostsBreakdown = (
   route: RouteExtended,
-  included = false
-) => {
+  included: boolean = false
+): {
+  gasCosts: FeesBreakdown[]
+  feeCosts: FeesBreakdown[]
+  gasCostUSD: number
+  feeCostUSD: number
+  combinedFeesUSD: number
+} => {
   const gasCosts = getGasCostsBreakdown(route)
   const feeCosts = getFeeCostsBreakdown(route, included)
   const gasCostUSD = gasCosts.reduce(

package/src/utils/format.ts

@@ -10,7 +10,7 @@ export const usdDecimals = 2
 export function formatTokenAmount(
   amount: bigint | undefined,
   decimals: number
-) {
+): string {
   const formattedAmount = amount ? formatUnits(amount, decimals) : '0'
   const parsedAmount = Number.parseFloat(formattedAmount)
   if (!parsedAmount || Number.isNaN(Number(formattedAmount))) {
@@ -59,8 +59,8 @@ export function formatSlippage(
 export function formatInputAmount(
   amount: string,
   decimals: number | null = null,
-  returnInitial = false
-) {
+  returnInitial: boolean = false
+): string {
   if (!amount) {
     return amount
   }
@@ -116,7 +116,7 @@ export function formatTokenPrice(
   amount?: string | bigint,
   price?: string,
   decimals?: number
-) {
+): number {
   if (!amount || !price) {
     return 0
   }
@@ -146,7 +146,10 @@ const formatter = new Intl.NumberFormat('en', {
 /**
  * Convert price value to token amount
  */
-export function priceToTokenAmount(priceValue: string, priceUSD?: string) {
+export function priceToTokenAmount(
+  priceValue: string,
+  priceUSD?: string
+): string {
   if (!priceValue || !priceUSD) {
     return '0'
   }

package/src/utils/getActionMessage.ts

@@ -6,7 +6,7 @@ import type {
   Substatus,
 } from '@lifi/sdk'
 import type { TFunction } from 'i18next'
-import type { SubvariantOptions, WidgetSubvariant } from '../types/widget'
+import type { ModeOptions, WidgetMode } from '../types/widget.js'
 
 export function getActionMessage(
   t: TFunction,
@@ -14,8 +14,8 @@ export function getActionMessage(
   type: ExecutionActionType,
   status: ExecutionActionStatus,
   substatus?: Substatus,
-  subvariant?: WidgetSubvariant,
-  subvariantOptions?: SubvariantOptions
+  mode?: WidgetMode,
+  modeOptions?: ModeOptions
 ): {
   title?: string
   message?: string
@@ -25,12 +25,7 @@ export function getActionMessage(
     : undefined
   const title =
     messageWithSubstatus ??
-    actionStatusMessages[type]?.[status]?.(
-      t,
-      step,
-      subvariant,
-      subvariantOptions
-    )
+    actionStatusMessages[type]?.[status]?.(t, step, mode, modeOptions)
   return { title }
 }
 
@@ -42,8 +37,8 @@ const actionStatusMessages: Record<
       (
         t: TFunction,
         step: LiFiStepExtended,
-        subvariant?: WidgetSubvariant,
-        subvariantOptions?: SubvariantOptions
+        mode?: WidgetMode,
+        modeOptions?: ModeOptions
       ) => string
     >
   >
@@ -58,7 +53,7 @@ const actionStatusMessages: Record<
         tokenSymbol: step.action.fromToken.symbol,
       }),
     DONE: (t, step) =>
-      t('main.process.tokenAllowance.pending', {
+      t('main.process.tokenAllowance.done', {
         tokenSymbol: step.action.fromToken.symbol,
       }),
   },
@@ -115,9 +110,9 @@ const actionStatusMessages: Record<
     ACTION_REQUIRED: (t) => t('main.process.swap.actionRequired'),
     MESSAGE_REQUIRED: (t) => t('main.process.swap.messageRequired'),
     PENDING: (t) => t('main.process.swap.pending'),
-    DONE: (t, _, subvariant, subvariantOptions) =>
-      subvariant === 'custom'
-        ? t(`main.process.${subvariantOptions?.custom ?? 'checkout'}.done`)
+    DONE: (t, _, mode, modeOptions) =>
+      mode === 'custom'
+        ? t(`main.process.${modeOptions?.custom?.type ?? 'checkout'}.done`)
         : t('main.process.swap.done'),
   },
   CROSS_CHAIN: {
@@ -130,9 +125,9 @@ const actionStatusMessages: Record<
   RECEIVING_CHAIN: {
     STARTED: (t) => t('main.process.receivingChain.pending'),
     PENDING: (t) => t('main.process.receivingChain.pending'),
-    DONE: (t, _, subvariant, subvariantOptions) =>
-      subvariant === 'custom'
-        ? t(`main.process.${subvariantOptions?.custom ?? 'checkout'}.done`)
+    DONE: (t, _, mode, modeOptions) =>
+      mode === 'custom'
+        ? t(`main.process.${modeOptions?.custom?.type ?? 'checkout'}.done`)
         : t('main.process.receivingChain.done'),
   },
 }

package/src/utils/getErrorMessage.ts

@@ -12,7 +12,7 @@ export function getErrorMessage(
   getChainById: (chainId: number) => EVMChain | undefined,
   step: LiFiStepExtended,
   failedAction?: ExecutionAction
-) {
+): { title: string; message: string } {
   const error = failedAction?.error
   if (!error) {
     return {

package/src/utils/getPriceImpact.ts

@@ -13,7 +13,7 @@ export const getPriceImpact = ({
   toToken,
   fromAmount,
   toAmount,
-}: GetPriceImpactProps) => {
+}: GetPriceImpactProps): number => {
   const fromTokenPrice = formatTokenPrice(
     fromAmount,
     fromToken.priceUSD,

package/src/utils/input.ts

@@ -2,7 +2,7 @@ export const fitInputText = (
   maxFontSize: number,
   minFontSize: number,
   element: HTMLElement
-) => {
+): void => {
   if (!element) {
     return
   }

package/src/utils/item.ts

@@ -55,7 +55,7 @@ export const isFormItemAllowed = <T>(
   configTokens: AllowDenySets | undefined,
   formType?: FormType,
   getKey?: (item: T) => AllowDenySetItem
-) => {
+): boolean => {
   return (
     isItemAllowedForSets(item, configTokens, getKey) &&
     (formType

package/src/utils/mode.ts

@@ -0,0 +1,13 @@
+import type { SplitMode, SplitModeOptions } from '../types/widget.js'
+
+export const getSplitMode = (
+  split?: SplitMode | SplitModeOptions
+): SplitMode => {
+  if (!split) {
+    return 'swap'
+  }
+  if (typeof split === 'string') {
+    return split
+  }
+  return split.defaultTab
+}

package/src/utils/navigationRoutes.ts

@@ -1,6 +1,6 @@
 export const navigationRoutes = {
   home: '/',
-  activeTransactions: 'active-transactions',
+  activities: 'activities',
   bridges: 'bridges',
   exchanges: 'exchanges',
   fromChain: 'from-chain',
@@ -13,7 +13,6 @@ export const navigationRoutes = {
   toTokenNative: 'to-token-native',
   transactionDetails: 'transaction-details',
   transactionExecution: 'transaction-execution',
-  transactionHistory: 'transaction-history',
   sendToWallet: 'send-to-wallet',
   bookmarks: 'bookmarks',
   recentWallets: 'recent-wallets',
@@ -21,10 +20,10 @@ export const navigationRoutes = {
   configuredWallets: 'configured-wallets',
 }
 
-export const navigationRoutesValues = Object.values(navigationRoutes)
+export const navigationRoutesValues: string[] = Object.values(navigationRoutes)
 
-export const stickyHeaderRoutes = [
-  navigationRoutes.activeTransactions,
+export const stickyHeaderRoutes: string[] = [
+  navigationRoutes.activities,
   navigationRoutes.bridges,
   navigationRoutes.exchanges,
   navigationRoutes.fromChain,
@@ -35,7 +34,6 @@ export const stickyHeaderRoutes = [
   navigationRoutes.toTokenNative,
   navigationRoutes.transactionDetails,
   navigationRoutes.transactionExecution,
-  navigationRoutes.transactionHistory,
   navigationRoutes.sendToWallet,
   navigationRoutes.bookmarks,
   navigationRoutes.recentWallets,
@@ -43,8 +41,8 @@ export const stickyHeaderRoutes = [
   navigationRoutes.configuredWallets,
 ]
 
-export const backButtonRoutes = [
-  navigationRoutes.activeTransactions,
+export const backButtonRoutes: string[] = [
+  navigationRoutes.activities,
   navigationRoutes.bridges,
   navigationRoutes.exchanges,
   navigationRoutes.languages,
@@ -57,7 +55,6 @@ export const backButtonRoutes = [
   navigationRoutes.toTokenNative,
   navigationRoutes.transactionDetails,
   navigationRoutes.transactionExecution,
-  navigationRoutes.transactionHistory,
   navigationRoutes.sendToWallet,
   navigationRoutes.bookmarks,
   navigationRoutes.recentWallets,

package/src/utils/percentFormatter.ts

@@ -4,7 +4,10 @@
  * +0.007% -> <0.01%
  * -0.003% -> <0.01%
  */
-export const percentFormatter = (lng: string | undefined, options: any) => {
+export const percentFormatter = (
+  lng: string | undefined,
+  options: any
+): ((value: any) => string) => {
   const formatter = new Intl.NumberFormat(lng, {
     ...options,
     style: 'percent',

package/src/utils/timer.ts

@@ -1,3 +1,13 @@
+import type { LiFiStepExtended } from '@lifi/sdk'
+
+export function getExpiryTimestamp(step?: LiFiStepExtended): Date {
+  const { signedAt } = step?.execution ?? {}
+  if (!step || !signedAt) {
+    return new Date()
+  }
+  return new Date(signedAt + step.estimate.executionDuration * 1000)
+}
+
 export const formatTimer = ({
   days = 0,
   hours = 0,