@lifi/widget 4.7.1 → 4.9.0

package/src/queries/types.ts

@@ -0,0 +1,38 @@
+import type {
+  QueryFunction,
+  QueryKey,
+  UseQueryOptions,
+} from '@tanstack/react-query'
+
+export type ScopeKeyParameter = {
+  /**
+   * Scopes the entry inside a shared `QueryClient`, like wagmi's `scopeKey`.
+   * Callers that pass the same value share the cached data; a widget passes
+   * its `queryScopeKey`.
+   */
+  scopeKey?: string | undefined
+}
+
+/**
+ * Behaviour the caller owns — `staleTime`, `refetchInterval`, `select`,
+ * `enabled`, … It is spread into the options and never becomes part of the
+ * key, so callers with different behaviour still share one entry.
+ */
+export type QueryParameter<queryFnData, data, queryKey extends QueryKey> = {
+  query?:
+    | Omit<
+        UseQueryOptions<queryFnData, Error, data, queryKey>,
+        'queryKey' | 'queryFn'
+      >
+    | undefined
+}
+
+/** Options ready for `useQuery`, `fetchQuery` or `prefetchQuery`. */
+export type FactoryQueryOptions<
+  queryFnData,
+  data,
+  queryKey extends QueryKey,
+> = UseQueryOptions<queryFnData, Error, data, queryKey> & {
+  queryKey: queryKey
+  queryFn: QueryFunction<queryFnData, queryKey>
+}

package/src/shared.ts

@@ -188,5 +188,6 @@ export {
 export { getPriceImpact } from './utils/getPriceImpact.js'
 export { fitInputText } from './utils/input.js'
 export { navigationRoutes } from './utils/navigationRoutes.js'
+export { resolveStorageScopeKey } from './utils/scopeKeys.js'
 export { isHttpUrl, openInNewTab } from './utils/url.js'
 export { shortenAddress } from './utils/wallet.js'

package/src/stores/StoreProvider.test.tsx

@@ -0,0 +1,107 @@
+/** @vitest-environment happy-dom */
+
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WidgetConfig } from '../types/widget.js'
+
+/**
+ * The persisted stores are named from the resolved storage scope. An
+ * integration that only set the deprecated keyPrefix must keep the store
+ * names it always had, or its users lose their saved state.
+ */
+
+const { recorded, recorder } = vi.hoisted(() => {
+  const recorded = { namePrefix: {} as Record<string, string | undefined> }
+  const recorder = (name: string) => ({
+    [name]: ({
+      children,
+      namePrefix,
+    }: {
+      children?: unknown
+      namePrefix?: string
+    }) => {
+      recorded.namePrefix[name] = namePrefix
+      return children
+    },
+  })
+  return { recorded, recorder }
+})
+
+vi.mock('./bookmarks/BookmarkStore.js', () => recorder('BookmarkStoreProvider'))
+vi.mock('./chains/ChainOrderStore.js', () =>
+  recorder('ChainOrderStoreProvider')
+)
+vi.mock('./form/FormStore.js', () => recorder('FormStoreProvider'))
+vi.mock('./header/useHeaderStore.js', () => recorder('HeaderStoreProvider'))
+vi.mock('./navigationTabs/useNavigationTabsStore.js', () =>
+  recorder('NavigationTabsStoreProvider')
+)
+vi.mock('./pinnedTokens/PinnedTokensStore.js', () =>
+  recorder('PinnedTokensStoreProvider')
+)
+vi.mock('./recentTokens/RecentTokensStore.js', () =>
+  recorder('RecentTokensStoreProvider')
+)
+vi.mock('./routes/RouteExecutionStore.js', () =>
+  recorder('RouteExecutionStoreProvider')
+)
+
+import { StoreProvider } from './StoreProvider.js'
+
+const PERSISTED = [
+  'BookmarkStoreProvider',
+  'PinnedTokensStoreProvider',
+  'RecentTokensStoreProvider',
+  'ChainOrderStoreProvider',
+  'RouteExecutionStoreProvider',
+]
+
+let root: Root
+
+const render = async (config: WidgetConfig) => {
+  await act(async () => {
+    root.render(<StoreProvider config={config}>{null}</StoreProvider>)
+  })
+}
+
+describe('StoreProvider storage scope', () => {
+  beforeEach(() => {
+    recorded.namePrefix = {}
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    await act(async () => root.unmount())
+  })
+
+  it('names the persisted stores from keyPrefix when only that is set', async () => {
+    await render({ integrator: 'test', keyPrefix: 'legacy' })
+
+    for (const store of PERSISTED) {
+      expect(recorded.namePrefix[store]).toBe('legacy')
+    }
+  })
+
+  it('names the persisted stores from storageScopeKey over keyPrefix', async () => {
+    await render({
+      integrator: 'test',
+      keyPrefix: 'legacy',
+      storageScopeKey: 'store',
+    })
+
+    for (const store of PERSISTED) {
+      expect(recorded.namePrefix[store]).toBe('store')
+    }
+  })
+
+  it('keeps the historical names when nothing is set', async () => {
+    await render({ integrator: 'test' })
+
+    for (const store of PERSISTED) {
+      expect(recorded.namePrefix[store]).toBeUndefined()
+    }
+  })
+})

package/src/stores/StoreProvider.tsx

@@ -1,5 +1,6 @@
 import type { PropsWithChildren } from 'react'
 import type { WidgetConfigProps } from '../types/widget.js'
+import { resolveStorageScopeKey } from '../utils/scopeKeys.js'
 import { BookmarkStoreProvider } from './bookmarks/BookmarkStore.js'
 import { ChainOrderStoreProvider } from './chains/ChainOrderStore.js'
 import { FormStoreProvider } from './form/FormStore.js'
@@ -14,15 +15,16 @@ export const StoreProvider: React.FC<PropsWithChildren<WidgetConfigProps>> = ({
   config,
   formRef,
 }) => {
+  const storageScopeKey = resolveStorageScopeKey(config)
   return (
     <NavigationTabsStoreProvider config={config}>
-      <HeaderStoreProvider namePrefix={config?.keyPrefix}>
-        <BookmarkStoreProvider namePrefix={config?.keyPrefix}>
-          <PinnedTokensStoreProvider namePrefix={config?.keyPrefix}>
-            <RecentTokensStoreProvider namePrefix={config?.keyPrefix}>
+      <HeaderStoreProvider>
+        <BookmarkStoreProvider namePrefix={storageScopeKey}>
+          <PinnedTokensStoreProvider namePrefix={storageScopeKey}>
+            <RecentTokensStoreProvider namePrefix={storageScopeKey}>
               <FormStoreProvider formRef={formRef}>
-                <ChainOrderStoreProvider namePrefix={config?.keyPrefix}>
-                  <RouteExecutionStoreProvider namePrefix={config?.keyPrefix}>
+                <ChainOrderStoreProvider namePrefix={storageScopeKey}>
+                  <RouteExecutionStoreProvider namePrefix={storageScopeKey}>
                     {children}
                   </RouteExecutionStoreProvider>
                 </ChainOrderStoreProvider>

package/src/stores/bookmarks/types.ts

@@ -1,8 +1,11 @@
+import type { ChainId } from '@lifi/sdk'
 import type { StoreApi, UseBoundStore } from 'zustand'
 import type { ToAddress } from '../../types/widget.js'
 
 export interface Bookmark extends ToAddress {
   isConnectedAccount?: boolean
+  /** Display only: set when the ecosystem's default chain rejects the address. */
+  chainId?: ChainId
 }
 
 export interface BookmarkProps {

package/src/stores/chains/ChainOrderStore.tsx

@@ -80,7 +80,10 @@ export function ChainOrderStoreProvider({
 
         // Initialize the isAllNetworks with true if the tab is shown,
         // there is no config chain value and no url chain value
-        const urlValues = getDefaultValuesFromQueryString({ buildUrl })
+        const urlValues = getDefaultValuesFromQueryString({
+          buildUrl,
+          chains: chainsConfig,
+        })
         const urlChainValue =
           key === 'from' ? urlValues.fromChain : urlValues.toChain
         const configChainValue =

package/src/stores/form/FormStore.tsx

@@ -45,6 +45,7 @@ export const FormStoreProvider: React.FC<FormStoreProviderProps> = ({
     toAddress,
     formUpdateKey,
     buildUrl,
+    chains,
   } = widgetConfig
 
   const storeRef = useRef<FormStoreStore>(null)
@@ -113,6 +114,7 @@ export const FormStoreProvider: React.FC<FormStoreProviderProps> = ({
     const queryDefaults = getDefaultValuesFromQueryString({
       buildUrl,
       includeToAddress: false,
+      chains,
     })
     storeRef.current = createFormStore(
       initialiseDefaultValues({

package/src/stores/form/URLSearchParamsBuilder.tsx

@@ -34,16 +34,17 @@ export const URLSearchParamsBuilder = () => {
   const values = useFieldValues(...formValueKeys, ...limitFormValueKeys)
   const { setSelectedBookmark, addRecentWallet } = useBookmarkActions()
   const { validateAddress } = useAddressValidation()
-  const { buildUrl, mode } = useWidgetConfig()
+  const { buildUrl, mode, chains } = useWidgetConfig()
   // Using these methods as trying to use the touchedFields and values above
   // often has a lag that can effect the widgets initialisation sequence
   // and accidentally cause values to be wiped from the query string
   const { getFieldValues, isTouched, setUserAndDefaultValues } =
     useFieldActions()
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the URL is read once, not again on each config render
   useEffect(() => {
     // get the initial values from the querystring
-    const formValues = getDefaultValuesFromQueryString({ buildUrl })
+    const formValues = getDefaultValuesFromQueryString({ buildUrl, chains })
     const { toAddress, ...initialFormValues } = formValues
 
     /**
@@ -62,6 +63,7 @@ export const URLSearchParamsBuilder = () => {
             const bookmark = {
               address: validationResult.address,
               chainType: validationResult.chainType,
+              chainId: validationResult.chainId,
             }
             setUserAndDefaultValues({ toAddress })
             setSelectedBookmark(bookmark)

package/src/stores/form/getDefaultValuesFromQueryString.ts

@@ -1,14 +1,21 @@
+import type { WidgetChains } from '../../types/widget.js'
+import {
+  isDestinationOnlyChain,
+  isUnservedDestinationChain,
+} from '../../utils/chainType.js'
 import { formatInputAmount } from '../../utils/format.js'
 import type { DefaultValues } from './types.js'
 
 interface GetDefaultValuesFromQueryStringOptions {
   includeToAddress?: boolean
   buildUrl?: boolean
+  chains?: WidgetChains
 }
 
 export const getDefaultValuesFromQueryString = ({
   buildUrl = false,
   includeToAddress = true,
+  chains,
 }: GetDefaultValuesFromQueryStringOptions): Partial<DefaultValues> => {
   if (typeof window === 'undefined') {
     return {}
@@ -22,6 +29,18 @@ export const getDefaultValuesFromQueryString = ({
     new URLSearchParams(window.location.search)
   )
 
+  // The loop below then drops their tokens too.
+  if (isDestinationOnlyChain(Number.parseInt(searchParams.fromChain, 10))) {
+    delete searchParams.fromChain
+  }
+  if (
+    isUnservedDestinationChain(
+      Number.parseInt(searchParams.toChain, 10),
+      chains
+    )
+  ) {
+    delete searchParams.toChain
+  }
   // Prevent using fromToken/toToken params if chain is not selected.
   ;(['from', 'to'] as const).forEach((key) => {
     if (searchParams[`${key}Token`] && !searchParams[`${key}Chain`]) {

package/src/stores/header/useHeaderStore.tsx

@@ -1,14 +1,13 @@
+import type { PropsWithChildren } from 'react'
 import { createContext, use, useRef } from 'react'
 import { create } from 'zustand'
 import { useShallow } from 'zustand/shallow'
-import type { PersistStoreProviderProps } from '../types.js'
 import type { HeaderState, HeaderStore } from './types.js'
 
 const HeaderStoreContext = createContext<HeaderStore | null>(null)
 
-export function HeaderStoreProvider({
-  children,
-}: PersistStoreProviderProps): any {
+// Not persisted, so it takes no storage scope.
+export function HeaderStoreProvider({ children }: PropsWithChildren): any {
   const storeRef = useRef<HeaderStore>(null)
   if (!storeRef.current) {
     storeRef.current = createHeaderStore()

package/src/types/widget.ts

@@ -410,7 +410,37 @@ export interface WidgetConfig {
   sdkConfig?: WidgetSDKConfig
 
   buildUrl?: boolean
+  /**
+   * @deprecated Use `storageScopeKey` for persisted state and `queryScopeKey`
+   * for the query cache. Still honoured as the fallback for both.
+   */
   keyPrefix?: string
+  /**
+   * Namespaces the widget's persisted state in `localStorage`: bookmarks,
+   * pinned tokens, recent tokens, chain order and route history, as
+   * `keyPrefix` does. Use a different value per widget instance that should
+   * keep its own state. Settings keep one shared name.
+   *
+   * It also scopes the widget's other queries (routes, tokens, balances, …),
+   * so instances with different values keep their data apart.
+   *
+   * Falls back to `keyPrefix`, then to the historical `li.fi-*` names.
+   */
+  storageScopeKey?: string
+  /**
+   * Scopes the widget's chains and tools queries inside the host's react-query
+   * `QueryClient`. Widget instances - and a host app using the
+   * `@lifi/widget/queries` factories - that pass the same value
+   * share those entries. The other widget queries are scoped by
+   * `storageScopeKey`.
+   *
+   * The keys start with a plain `'chains'` / `'tools'`, as in wagmi, so a host
+   * that matches on those roots (for example `setQueriesData({ queryKey:
+   * ['chains'] })`) also reaches the widget's entries.
+   *
+   * Falls back to `keyPrefix`, then to `'li.fi'`.
+   */
+  queryScopeKey?: string
 
   bridges?: AllowDeny<string>
   exchanges?: AllowDeny<string>

package/src/utils/chainType.ts

@@ -1,4 +1,6 @@
-import { ChainId, ChainType } from '@lifi/sdk'
+import { ChainId, ChainType, type SDKProvider } from '@lifi/sdk'
+import type { WidgetChains, WidgetConfig } from '../types/widget.js'
+import { isItemAllowed } from './item.js'
 
 export const defaultChainIdsByType: Record<ChainType, ChainId> = {
   [ChainType.EVM]: ChainId.ETH,
@@ -8,3 +10,73 @@ export const defaultChainIdsByType: Record<ChainType, ChainId> = {
   [ChainType.TVM]: ChainId.TRN,
   [ChainType.STL]: ChainId.XLM,
 }
+
+// No wallet can sign on these chains yet, so a route may only deliver to them.
+const destinationOnlyChainIds: ReadonlySet<number> = new Set<number>([
+  ChainId.ZEC,
+])
+
+export const isDestinationOnlyChain = (chainId?: number): boolean =>
+  chainId !== undefined && destinationOnlyChainIds.has(chainId)
+
+export const withDestinationOnlyChains = (
+  chains: WidgetChains | undefined
+): WidgetChains => {
+  const allow = chains?.from?.allow?.filter(
+    (chainId) => !isDestinationOnlyChain(chainId)
+  )
+  return {
+    ...chains,
+    from: {
+      ...chains?.from,
+      ...(allow && { allow }),
+      deny: [...(chains?.from?.deny ?? []), ...destinationOnlyChainIds],
+    },
+  }
+}
+
+// A destination-only chain takes a receiver only through a provider that lists it.
+export const withServedDestinationChains = (
+  chains: WidgetChains | undefined,
+  providers: readonly Pick<SDKProvider, 'chainIds'>[]
+): WidgetChains | undefined => {
+  const unserved = [...destinationOnlyChainIds].filter(
+    (chainId) =>
+      !providers.some((provider) =>
+        provider.chainIds?.some((id) => id === chainId)
+      )
+  )
+  if (!unserved.length) {
+    return chains
+  }
+  const allow = chains?.allow?.filter((chainId) => !unserved.includes(chainId))
+  return {
+    ...chains,
+    ...(allow && { allow }),
+    deny: [...(chains?.deny ?? []), ...unserved],
+  }
+}
+
+// The form keeps a preset chain that the chain list does not offer.
+export const isUnservedDestinationChain = (
+  chainId: number | undefined,
+  chains: WidgetChains | undefined
+): boolean => isDestinationOnlyChain(chainId) && !isItemAllowed(chainId, chains)
+
+// Omitted, not undefined: an own undefined key resets the form field.
+export const withoutUnservedToChain = <
+  T extends Pick<WidgetConfig, 'chains' | 'toChain' | 'toToken'>,
+>(
+  config: T
+): T => {
+  if (!isUnservedDestinationChain(config.toChain, config.chains)) {
+    return config
+  }
+  const { toChain: _toChain, toToken: _toToken, ...rest } = config
+  return rest as T
+}
+
+export const isDestinationAllowedAsSource = (
+  toChainId: number | undefined,
+  chains: WidgetChains | undefined
+): boolean => !toChainId || isItemAllowed(toChainId, chains?.from)

package/src/utils/customReceiver.ts

@@ -1,4 +1,5 @@
 import { ChainType } from '@lifi/sdk'
+import type { ChainRef, IsAddressForChain } from '@lifi/widget-provider'
 
 // Stellar routes always settle to the account that signs them.
 export const isCustomReceiverUnsupported = (
@@ -29,3 +30,38 @@ export const isCustomReceiverBlocked = ({
   }
   return toAddress.toLowerCase() !== signerAddress?.toLowerCase()
 }
+
+// Without a receiver the API delivers to the signer when both chains share a
+// chain type, and a Bitcoin signer cannot receive on ZEC.
+export const isSignerInvalidReceiver = ({
+  signerAddress,
+  toAddress,
+  fromChain,
+  toChain,
+  isAddressForChain,
+}: {
+  signerAddress: string | undefined
+  toAddress: string | undefined
+  fromChain: ChainRef | undefined
+  toChain: ChainRef | undefined
+  isAddressForChain: IsAddressForChain
+}): boolean =>
+  Boolean(
+    signerAddress &&
+      !toAddress &&
+      fromChain &&
+      toChain &&
+      fromChain.chainType === toChain.chainType &&
+      !isAddressForChain(signerAddress, toChain)
+  )
+
+export const canQuoteWithToAddress = (
+  toAddress: string | undefined,
+  toChain: ChainRef | undefined,
+  isAddressForChain: IsAddressForChain
+): boolean => {
+  if (!toAddress) {
+    return true
+  }
+  return toChain ? isAddressForChain(toAddress, toChain) : false
+}

package/src/utils/queries.ts

@@ -1,2 +1,3 @@
+// Legacy keys: callers pass the storage scope, so instances stay apart.
 export const getQueryKey = (key: string, prefix?: string) =>
   `${prefix || 'li.fi'}-widget-${key}`

package/src/utils/scopeKeys.ts

@@ -0,0 +1,18 @@
+import type { WidgetConfig } from '../types/widget.js'
+
+// Non-empty, so an unconfigured widget never shares a host's unscoped entries.
+export const defaultQueryScopeKey = 'li.fi'
+
+type ScopeKeyConfig = Pick<
+  WidgetConfig,
+  'storageScopeKey' | 'queryScopeKey' | 'keyPrefix'
+>
+
+// `undefined` keeps the historical `li.fi-*` store names.
+export const resolveStorageScopeKey = (
+  config: Partial<ScopeKeyConfig> | undefined
+): string | undefined => config?.storageScopeKey ?? config?.keyPrefix
+
+export const resolveQueryScopeKey = (
+  config: Partial<ScopeKeyConfig> | undefined
+): string => config?.queryScopeKey ?? config?.keyPrefix ?? defaultQueryScopeKey