@lifi/widget 0.0.0-preview-6cc63bac

package/src/types/widget.ts

@@ -0,0 +1,441 @@
+import type {
+  BaseToken,
+  ChainType,
+  ContractCall,
+  ExecutionOptions,
+  ExtendedChain,
+  Order,
+  Route,
+  RouteOptions,
+  SDKConfig,
+  StaticToken,
+  Token,
+} from '@lifi/sdk'
+import type { WalletMenuOpenArgs } from '@lifi/wallet-management'
+import type { WidgetProviderProps } from '@lifi/widget-provider'
+import type {
+  Components,
+  PaletteMode,
+  PaletteOptions,
+  Shape,
+  SxProps,
+  Theme,
+} from '@mui/material'
+import type { TypographyVariantsOptions } from '@mui/material/styles'
+import type {
+  CSSProperties,
+  PropsWithChildren,
+  ReactNode,
+  RefObject,
+} from 'react'
+import type {
+  LanguageKey,
+  LanguageResources,
+} from '../providers/I18nProvider/types.js'
+import type { DefaultFieldValues } from '../stores/form/types.js'
+
+export type WidgetVariant = 'compact' | 'wide' | 'drawer'
+export type WidgetMode = 'default' | 'split' | 'custom' | 'refuel'
+export type SplitMode = 'bridge' | 'swap'
+export type SplitModeOptions = {
+  defaultTab: SplitMode
+}
+export type CustomMode = 'checkout' | 'deposit'
+export interface ModeOptions {
+  /**
+   * Configure split mode behavior:
+   * - 'bridge' | 'swap': Single mode without tabs
+   * - { defaultTab: 'bridge' | 'swap' }: Tabs mode with configurable default tab
+   */
+  split?: SplitMode | SplitModeOptions
+  custom?: { type: CustomMode }
+}
+
+export type Appearance = PaletteMode | 'system'
+export interface NavigationProps {
+  /**
+   * If given, uses a negative margin to counteract the padding on sides for navigation elements like icon buttons.
+   * @default true
+   */
+  edge?: boolean
+}
+export type WidgetThemeComponents = Partial<
+  Pick<
+    Components<Theme>,
+    | 'MuiAppBar'
+    | 'MuiAvatar'
+    | 'MuiButton'
+    | 'MuiCard'
+    | 'MuiDrawer'
+    | 'MuiIconButton'
+    | 'MuiInputCard'
+    | 'MuiNavigationTabs'
+    | 'MuiNavigationTab'
+    | 'MuiTabs'
+    | 'MuiCheckbox'
+  >
+>
+
+export type WidgetTheme = {
+  colorSchemes?: {
+    light?: {
+      palette: PaletteOptions
+    }
+    dark?: {
+      palette: PaletteOptions
+    }
+  }
+  shape?: Partial<Shape>
+  typography?: TypographyVariantsOptions
+  components?: WidgetThemeComponents
+  container?: CSSProperties
+  routesContainer?: CSSProperties
+  chainSidebarContainer?: CSSProperties
+  header?: CSSProperties
+  navigation?: NavigationProps
+}
+
+export interface DisabledUIConfig {
+  fromAmount?: boolean
+  fromToken?: boolean
+  toAddress?: boolean
+  toToken?: boolean
+}
+
+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 interface RequiredUIConfig {
+  accountDeployedMessage?: boolean
+  toAddress?: boolean
+}
+
+export type DefaultUI = {
+  transactionDetailsExpanded?: boolean
+  navigationHeaderTitleNoWrap?: boolean
+}
+
+export interface WidgetWalletConfig {
+  walletEcosystemsOrder?: Record<string, ChainType[]>
+  onConnect?(args?: WalletMenuOpenArgs): void
+  /**
+   * Determines whether the widget should provide partial wallet management functionality.
+   *
+   * In partial mode, external wallet management will be used for "opt-out" providers,
+   * while the internal management is applied for any remaining providers that do not opt out.
+   * This allows a flexible balance between the integrator's custom wallet menu and the widget's native wallet menu.
+   * @default false
+   */
+  usePartialWalletManagement?: boolean
+  /**
+   * This option forces the widget to always use internal wallet management ignoring external wallet management contexts
+   * @default false
+   */
+  forceInternalWalletManagement?: boolean
+}
+
+export interface WidgetSDKConfig
+  extends Omit<
+    SDKConfig,
+    | 'apiKey'
+    | 'disableVersionCheck'
+    | 'integrator'
+    | 'providers'
+    | 'routeOptions'
+    | 'widgetVersion'
+  > {
+  routeOptions?: Omit<
+    RouteOptions,
+    'bridges' | 'exchanges' | 'fee' | 'referrer' | 'order' | 'slippage'
+  >
+  executionOptions?: Pick<ExecutionOptions, 'updateTransactionRequestHook'>
+}
+
+export interface WidgetContractTool {
+  name: string
+  logoURI: string
+}
+
+export interface CalculateFeeParams {
+  fromChain: ExtendedChain
+  toChain: ExtendedChain
+  fromToken: Token
+  toToken: Token
+  fromAddress?: string
+  toAddress?: string
+  fromAmount?: bigint
+  toAmount?: bigint
+  slippage?: number
+}
+
+export interface WidgetFeeConfig {
+  name?: string
+  logoURI?: string
+  fee?: number
+  /**
+   * Whether to show the fee percentage in the fee details.
+   * @default false
+   */
+  showFeePercentage?: boolean
+  /**
+   * Whether to show a tooltip with the fee details. Requires `name` or `feeTooltipComponent` to be set.
+   * @default false
+   */
+  showFeeTooltip?: boolean
+  /**
+   * Custom tooltip component to show with the fee details.
+   */
+  feeTooltipComponent?: ReactNode
+  /**
+   * Function to calculate fees before fetching quotes.
+   * If provided, this function will be used instead of the `fee` parameter.
+   * Only one of `fee` or `calculateFee` should be used.
+   *
+   * @param params Object containing the fee calculation parameters
+   * @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>
+}
+
+export interface ToAddress {
+  name?: string
+  address: string
+  chainType: ChainType
+  logoURI?: string
+}
+
+export interface AllowDeny<T> {
+  allow?: T[]
+  deny?: T[]
+}
+
+export type AllowDenySetItem = string | number
+export interface AllowDenySet {
+  allow?: Set<AllowDenySetItem>
+  deny?: Set<AllowDenySetItem>
+}
+
+export type AllowDenySets = {
+  from?: AllowDenySet
+  to?: AllowDenySet
+} & AllowDenySet
+
+export type AllowDenyItems<T> = {
+  from?: AllowDeny<T>
+  to?: AllowDeny<T>
+} & AllowDeny<T>
+
+export type WidgetChains = {
+  types?: AllowDeny<ChainType>
+} & AllowDenyItems<number>
+
+export type WidgetTokens = {
+  featured?: StaticToken[]
+  include?: Token[]
+  popular?: StaticToken[]
+} & AllowDenyItems<BaseToken>
+
+export type WidgetLanguages = {
+  default?: LanguageKey
+} & AllowDeny<LanguageKey>
+
+export type PoweredByType = 'default' | 'jumper'
+
+export interface RouteLabel {
+  text: string
+  sx?: SxProps<Theme>
+}
+
+export interface RouteLabelRule {
+  label: RouteLabel
+  // Matching criteria
+  bridges?: AllowDeny<string>
+  exchanges?: AllowDeny<string>
+  fromChainId?: number[]
+  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 =
+  | string
+  | {
+      url: string
+      txPath?: string
+      addressPath?: string
+    }
+
+export type WidgetProvider = (
+  props: PropsWithChildren<WidgetProviderProps>
+) => ReactNode
+
+export interface WidgetConfig {
+  fromChain?: number
+  toChain?: number
+  fromToken?: string
+  toToken?: string
+  toAddress?: ToAddress
+  toAddresses?: ToAddress[]
+  fromAmount?: number | string
+  minFromAmountUSD?: number
+  toAmount?: number | string
+  formUpdateKey?: string
+
+  providers?: WidgetProvider[]
+
+  contractCalls?: ContractCall[]
+  contractComponent?: ReactNode
+  contractSecondaryComponent?: ReactNode
+  contractCompactComponent?: ReactNode
+  contractTool?: WidgetContractTool
+  integrator: string
+  apiKey?: string
+  feeConfig?: WidgetFeeConfig
+  referrer?: string
+
+  routePriority?: Order
+  slippage?: number
+
+  variant?: WidgetVariant
+  mode?: WidgetMode
+  modeOptions?: ModeOptions
+
+  appearance?: Appearance
+  theme?: WidgetTheme
+
+  disabledUI?: DisabledUIConfig
+  hiddenUI?: HiddenUIConfig
+  requiredUI?: RequiredUIConfig
+  defaultUI?: DefaultUI
+  /**
+   * 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
+  sdkConfig?: WidgetSDKConfig
+
+  buildUrl?: boolean
+  keyPrefix?: string
+
+  bridges?: AllowDeny<string>
+  exchanges?: AllowDeny<string>
+  chains?: WidgetChains
+  tokens?: WidgetTokens
+  languages?: WidgetLanguages
+  languageResources?: LanguageResources
+  explorerUrls?: Record<number, ExplorerUrl[]> &
+    Partial<Record<'internal', ExplorerUrl[]>>
+  poweredBy?: PoweredByType
+
+  /**
+   * Custom labels/badges to show on routes based on specified rules
+   */
+  routeLabels?: RouteLabelRule[]
+}
+
+export interface FormFieldOptions {
+  setUrlSearchParam: boolean
+}
+
+export interface FieldValues
+  extends Omit<DefaultFieldValues, 'fromAmount' | 'toAmount' | 'toAddress'> {
+  fromAmount?: number | string
+  toAmount?: number | string
+  toAddress?: ToAddress | string
+}
+
+export type FieldNames = keyof FieldValues
+
+export type SetFieldValueFunction = <K extends FieldNames>(
+  key: K,
+  value: FieldValues[K],
+  options?: FormFieldOptions
+) => void
+
+export type FormState = {
+  setFieldValue: SetFieldValueFunction
+}
+
+export type FormRef = RefObject<FormState | null>
+
+export interface FormRefProps {
+  formRef?: FormRef
+}
+
+export interface WidgetConfigProps extends FormRefProps {
+  config: WidgetConfig
+}
+
+export interface WidgetConfigPartialProps {
+  config?: Partial<WidgetConfig>
+}
+
+export type WidgetProps = WidgetDrawerProps &
+  WidgetConfig &
+  WidgetConfigPartialProps &
+  FormRefProps
+
+export interface WidgetDrawerProps extends WidgetConfigPartialProps {
+  elementRef?: RefObject<HTMLDivElement>
+  open?: boolean
+  /**
+   * Make sure to make the onClose callback stable (e.g. using useCallback) to avoid causing re-renders of the entire widget
+   */
+  onClose?(): void
+}
+
+export enum ExpansionType {
+  Routes = 'routes',
+  FromChain = 'fromChain',
+  ToChain = 'toChain',
+}

package/src/utils/chainType.ts

@@ -0,0 +1,10 @@
+import { ChainId, ChainType } from '@lifi/sdk'
+
+export const defaultChainIdsByType: Record<ChainType, ChainId> = {
+  [ChainType.EVM]: ChainId.ETH,
+  [ChainType.SVM]: ChainId.SOL,
+  [ChainType.UTXO]: ChainId.BTC,
+  [ChainType.MVM]: ChainId.SUI,
+  [ChainType.TVM]: ChainId.TRN,
+  [ChainType.STL]: ChainId.XLM,
+}

package/src/utils/compactNumberFormatter.ts

@@ -0,0 +1,91 @@
+/**
+ * Converts a non-negative integer to its subscript representation using Unicode subscript characters.
+ * @param n - The number to convert to subscript
+ * @returns A string where each digit is converted to its subscript equivalent
+ * @example
+ * toSubscript(5) => '₅'
+ * toSubscript(10) => '₁₀'
+ */
+function toSubscript(n: number): string {
+  return n
+    .toString()
+    .split('')
+    .map((digit) => String.fromCharCode(8320 + Number(digit)))
+    .join('')
+}
+
+/**
+ * Formats numbers with special handling for small decimal values, converting runs of leading zeros
+ * into a more compact subscript notation.
+ *
+ * @param value - The numeric value to format (expected to be a string representing a BigInt)
+ * @param lng - The locale string for number formatting
+ * @param options - Formatting options including decimals and Intl.NumberFormat options
+ * @returns A formatted string with subscript notation for leading zeros
+ */
+export const compactNumberFormatter = (
+  lng: string | undefined,
+  options: any
+): ((value: any) => string) => {
+  const formatter = new Intl.NumberFormat(lng, {
+    notation: 'standard',
+    roundingPriority: 'morePrecision',
+    maximumSignificantDigits: 20,
+    maximumFractionDigits: 20,
+    ...options,
+  })
+  return (value: any) => {
+    if (!Number.parseFloat(value) || Number.isNaN(Number(value))) {
+      return '0'
+    }
+
+    const parts = formatter.formatToParts(value as Intl.StringNumericLiteral)
+    let integerPart = ''
+    let fractionPart = ''
+    let decimalSeparator = ''
+    let minusSign = ''
+
+    for (const p of parts) {
+      switch (p.type) {
+        case 'integer':
+        case 'group':
+          integerPart += p.value
+          break
+        case 'fraction':
+          fractionPart += p.value
+          break
+        case 'decimal':
+          decimalSeparator = p.value
+          break
+        case 'minusSign':
+          minusSign = p.value
+          break
+      }
+    }
+
+    // For numbers with no decimal part, return early
+    if (!fractionPart) {
+      return `${minusSign}${integerPart}`
+    }
+
+    // Count consecutive leading zeros in the fraction part
+    const match = fractionPart.match(/^0+/)
+    const leadingZerosCount = match ? match[0].length : 0
+
+    // For numbers with few leading zeros (≤ 3), format normally
+    // but limit the total length and trim trailing zeros
+    if (leadingZerosCount <= 3) {
+      fractionPart = fractionPart.slice(0, 6).replace(/0+$/, '')
+      return `${minusSign}${integerPart}${decimalSeparator}${fractionPart}`
+    }
+
+    // For numbers with many leading zeros (> 3), use subscript notation
+    // Format: "0.0₍number_of_zeros₎significant_digits"
+    const zerosSubscript = toSubscript(leadingZerosCount)
+    const remainder = fractionPart
+      .slice(leadingZerosCount, leadingZerosCount + 4)
+      .replace(/0+$/, '')
+
+    return `${minusSign}${integerPart}${decimalSeparator}0${zerosSubscript}${remainder}`
+  }
+}