@openzeppelin/ui-react 3.2.0 → 3.3.0

package/dist/index.cjs

@@ -33,7 +33,7 @@ let _tanstack_react_query = require("@tanstack/react-query");
 let _openzeppelin_ui_components = require("@openzeppelin/ui-components");
 
 //#region src/version.ts
-const VERSION = "3.2.0";
+const VERSION = "3.3.0";
 
 //#endregion
 //#region src/hooks/AdapterContext.tsx
@@ -1173,11 +1173,11 @@ const NOOP_RETRY = () => {};
 * {@link EngineResult}. Not exported from the package.
 */
 function useResolutionEngine(params) {
-	const { input, namespace, debounceMs, enabled, shouldAttempt, getMethod } = params;
+	const { input, namespace, debounceMs, enabled, shouldAttempt, getMethod, runtimeSource } = params;
 	const walletState = (0, react.useContext)(WalletStateContext);
-	const activeRuntime = walletState?.activeRuntime ?? null;
-	const activeNetworkId = walletState?.activeNetworkId ?? null;
-	const isRuntimeLoading = walletState?.isRuntimeLoading ?? false;
+	const activeRuntime = runtimeSource ? runtimeSource.runtime : walletState?.activeRuntime ?? null;
+	const activeNetworkId = runtimeSource ? runtimeSource.networkId : walletState?.activeNetworkId ?? null;
+	const isRuntimeLoading = runtimeSource ? runtimeSource.isRuntimeLoading : walletState?.isRuntimeLoading ?? false;
 	const { queryClient, config } = useNameResolutionContext();
 	const trimmedLive = (input ?? "").trim();
 	const normalizedLive = trimmedLive.toLowerCase();
@@ -1332,40 +1332,13 @@ function toNameResult(engine) {
 }
 
 //#endregion
-//#region src/hooks/nameResolution/useResolveAddress.ts
-/**
-* Reverse-resolve an address to a name. Soft-reads the active runtime from
-* `WalletStateContext` (never throws when no provider is mounted — degrades to
-* idle / UNSUPPORTED_NETWORK) and calls `runtime.nameResolution?.resolveAddress`.
-* Caches per (network, address) via the owned QueryClient. Not debounced by
-* default — addresses are pasted, not typed char-by-char.
-*
-* Applies no client-side address-shape check (INV-32): resolution is attempted on
-* any non-empty input and malformed addresses are rejected via the adapter's typed
-* error union. Address-shape validation is SF-3's concern.
-*
-* @param address - The address to reverse-resolve. `null` / empty yields
-*   `status: 'idle'`.
-* @param options - `debounceMs` / `enabled` overrides.
-* @returns The current {@link UseResolveAddressResult}.
-*/
-function useResolveAddress(address, options) {
-	const { config } = useNameResolutionContext();
-	return toAddressResult(useResolutionEngine({
-		input: address,
-		namespace: "addr",
-		debounceMs: options?.debounceMs ?? config.reverseDebounceMs,
-		enabled: options?.enabled ?? true,
-		shouldAttempt: () => true,
-		getMethod: (cap) => cap.resolveAddress
-	}));
-}
+//#region src/hooks/nameResolution/mapAddressEngineResult.ts
 /**
 * Remap the engine's generic `input` to `address` (INV-24). A `debouncing` arm —
 * only reachable when a caller passes a non-zero reverse `debounceMs` — collapses
 * to `loading` so {@link UseResolveAddressResult} keeps no `debouncing` variant.
 */
-function toAddressResult(engine) {
+function mapAddressEngineResult(engine) {
 	switch (engine.status) {
 		case "idle": return { status: "idle" };
 		case "debouncing":
@@ -1387,6 +1360,71 @@ function toAddressResult(engine) {
 	}
 }
 
+//#endregion
+//#region src/hooks/nameResolution/useNetworkRuntimeSource.ts
+/**
+* Soft-reads {@link RuntimeContext} (never throws) and requests the registry
+* runtime for `network`. Call during render so loading state updates propagate.
+*
+* Does not mutate {@link WalletStateProvider}'s active network — wallet-global
+* runtime is never consulted when a scoped network is supplied (INV-154).
+*/
+function useNetworkRuntimeSource(network) {
+	const runtimeContext = (0, react.useContext)(RuntimeContext);
+	if (!network) return {
+		runtime: null,
+		networkId: "",
+		isRuntimeLoading: false
+	};
+	if (!runtimeContext) return {
+		runtime: null,
+		networkId: network.id,
+		isRuntimeLoading: false
+	};
+	const { runtime, isLoading } = runtimeContext.getRuntimeForNetwork(network);
+	return {
+		runtime,
+		networkId: network.id,
+		isRuntimeLoading: isLoading
+	};
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useResolveAddress.ts
+/**
+* Reverse-resolve an address to a name. Soft-reads the active runtime from
+* `WalletStateContext` (never throws when no provider is mounted — degrades to
+* idle / UNSUPPORTED_NETWORK) and calls `runtime.nameResolution?.resolveAddress`.
+* Pass `options.network` to scope resolution to a specific network without
+* changing the wallet's active network. Caches per (network, address) via the
+* owned QueryClient. Not debounced by default — addresses are pasted, not
+* typed char-by-char.
+*
+* Applies no client-side address-shape check (INV-32): resolution is attempted on
+* any non-empty input and malformed addresses are rejected via the adapter's typed
+* error union. Address-shape validation is SF-3's concern.
+*
+* @param address - The address to reverse-resolve. `null` / empty yields
+*   `status: 'idle'`.
+* @param options - `debounceMs` / `enabled` / `network` overrides.
+* @returns The current {@link UseResolveAddressResult}.
+*/
+function useResolveAddress(address, options) {
+	const { config } = useNameResolutionContext();
+	const debounceMs = options?.debounceMs ?? config.reverseDebounceMs;
+	const enabled = options?.enabled ?? true;
+	const networkSource = useNetworkRuntimeSource(options?.network ?? null);
+	return mapAddressEngineResult(useResolutionEngine({
+		input: address,
+		namespace: "addr",
+		debounceMs,
+		enabled,
+		shouldAttempt: () => true,
+		getMethod: (cap) => cap.resolveAddress,
+		runtimeSource: options?.network != null ? networkSource : void 0
+	}));
+}
+
 //#endregion
 //#region src/hooks/nameResolution/NameResolutionProvider.tsx
 /**
@@ -1412,6 +1450,54 @@ function NameResolutionProvider({ children, config, queryClient }) {
 	});
 }
 
+//#endregion
+//#region src/hooks/nameResolution/createNameResolver.ts
+const EMPTY_RESOLVER$1 = {};
+/**
+* Projects a {@link NameResolutionCapability} into the SF-3 {@link NameResolver}
+* seam with SF-2 cache-key parity (INV-119).
+*/
+function createNameResolverFromCapability(capability, networkId, runtimeInstanceId, queryClient, config) {
+	if (!capability) return EMPTY_RESOLVER$1;
+	const resolveNameMethod = capability.resolveName;
+	return {
+		isValidName: (name) => capability.isValidName(name),
+		resolveName: resolveNameMethod ? async (name) => {
+			const normalized = name.trim().toLowerCase();
+			try {
+				return {
+					ok: true,
+					value: await queryClient.fetchQuery({
+						queryKey: buildResolutionKey("name", networkId, normalized, runtimeInstanceId),
+						queryFn: async () => {
+							let result;
+							try {
+								result = await resolveNameMethod(normalized);
+							} catch (cause) {
+								throw new ResolutionQueryError({
+									code: "ADAPTER_ERROR",
+									message: cause instanceof Error ? cause.message : String(cause),
+									cause
+								});
+							}
+							if (!result.ok) throw new ResolutionQueryError(result.error);
+							return result.value;
+						},
+						staleTime: config.staleTimeMs,
+						gcTime: config.gcTimeMs,
+						retry: (failureCount, error) => (error instanceof ResolutionQueryError ? isTransientError(error.resolutionError) : true) && failureCount < config.transientRetryCount
+					})
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: toNameResolutionError(error)
+				};
+			}
+		} : void 0
+	};
+}
+
 //#endregion
 //#region src/hooks/nameResolution/useRuntimeNameResolver.ts
 /**
@@ -1421,7 +1507,7 @@ function NameResolutionProvider({ children, config, queryClient }) {
 */
 const EMPTY_RESOLVER = {};
 /**
-* Project the active runtime's `NameResolutionCapability` into the injected
+* Project a runtime's `NameResolutionCapability` into the injected
 * {@link NameResolver} seam consumed by `@openzeppelin/ui-components` (SF-3, D3).
 * Mounted ambiently by the renderer:
 *
@@ -1429,6 +1515,10 @@ const EMPTY_RESOLVER = {};
 * <NameResolverProvider {...useRuntimeNameResolver()}>{form}</NameResolverProvider>
 * ```
 *
+* Pass `scopedNetwork` to resolve against a specific network via
+* {@link RuntimeProvider}'s registry without changing {@link WalletStateProvider}'s
+* active network (e.g. address-book Add Alias dropdown).
+*
 * Each imperative call is backed by SF-2's **owned** resolution `QueryClient`
 * via `fetchQuery`, reusing SF-2's exact query-key convention
 * (`buildResolutionKey('name', networkId, normalizedName)`) — so a name
@@ -1437,9 +1527,10 @@ const EMPTY_RESOLVER = {};
 * out-of-order safety, never a parallel cache (INV-119).
 *
 * Degradation, in order (all method-omission, never a throw):
-* - No `WalletStateProvider` mounted → empty resolver. The context is read
-*   directly (not via `useWalletState()`, which throws) so the ambient
-*   renderer mount stays safe for wallet-less usage.
+* - No `WalletStateProvider` mounted (wallet path) or no `RuntimeProvider`
+*   (network path) → empty resolver. The context is read directly (not via
+*   `useWalletState()`, which throws) so the ambient renderer mount stays safe
+*   for wallet-less usage.
 * - No active runtime, or runtime without the capability → empty resolver.
 * - Capability without `resolveName` → `isValidName` only; forward unsupported.
 *
@@ -1449,61 +1540,49 @@ const EMPTY_RESOLVER = {};
 *
 * @returns A referentially stable {@link NameResolver} for the active runtime.
 */
-function useRuntimeNameResolver() {
+function useRuntimeNameResolver(scopedNetwork) {
 	const walletState = (0, react.useContext)(WalletStateContext);
 	const { queryClient, config } = useNameResolutionContext();
-	const activeRuntime = walletState?.activeRuntime ?? null;
+	const networkSource = useNetworkRuntimeSource(scopedNetwork ?? null);
+	const useNetworkScoped = scopedNetwork != null;
+	const activeRuntime = useNetworkScoped ? networkSource.runtime : walletState?.activeRuntime ?? null;
 	const capability = activeRuntime?.nameResolution;
-	const networkId = walletState?.activeNetworkId ?? "";
+	const networkId = useNetworkScoped ? networkSource.networkId : walletState?.activeNetworkId ?? "";
 	const runtimeInstanceId = getRuntimeInstanceId(activeRuntime);
 	return (0, react.useMemo)(() => {
 		if (!capability) return EMPTY_RESOLVER;
-		const resolveNameMethod = capability.resolveName;
-		return {
-			isValidName: (name) => capability.isValidName(name),
-			resolveName: resolveNameMethod ? async (name) => {
-				const normalized = name.trim().toLowerCase();
-				try {
-					return {
-						ok: true,
-						value: await queryClient.fetchQuery({
-							queryKey: buildResolutionKey("name", networkId, normalized, runtimeInstanceId),
-							queryFn: async () => {
-								let result;
-								try {
-									result = await resolveNameMethod(normalized);
-								} catch (cause) {
-									throw new ResolutionQueryError({
-										code: "ADAPTER_ERROR",
-										message: cause instanceof Error ? cause.message : String(cause),
-										cause
-									});
-								}
-								if (!result.ok) throw new ResolutionQueryError(result.error);
-								return result.value;
-							},
-							staleTime: config.staleTimeMs,
-							gcTime: config.gcTimeMs,
-							retry: (failureCount, error) => (error instanceof ResolutionQueryError ? isTransientError(error.resolutionError) : true) && failureCount < config.transientRetryCount
-						})
-					};
-				} catch (error) {
-					return {
-						ok: false,
-						error: toNameResolutionError(error)
-					};
-				}
-			} : void 0
-		};
+		return createNameResolverFromCapability(capability, networkId, runtimeInstanceId, queryClient, config);
 	}, [
 		capability,
+		networkId,
+		runtimeInstanceId,
 		queryClient,
 		config,
-		networkId,
-		runtimeInstanceId
+		useNetworkScoped ? networkSource.isRuntimeLoading : walletState?.isRuntimeLoading ?? false
 	]);
 }
 
+//#endregion
+//#region src/hooks/nameResolution/useNetworkNameResolver.ts
+/**
+* @deprecated Pass the network to {@link useRuntimeNameResolver} instead.
+*/
+function useNetworkNameResolver(network) {
+	return useRuntimeNameResolver(network ?? void 0);
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useNetworkResolveAddress.ts
+/**
+* @deprecated Pass `network` in {@link UseResolveAddressOptions} to {@link useResolveAddress}.
+*/
+function useNetworkResolveAddress(address, network, options) {
+	return useResolveAddress(address, network != null ? {
+		...options,
+		network
+	} : options);
+}
+
 //#endregion
 //#region src/hooks/runtime/runtimeCreationConfig.ts
 /** Safe default: miss-fallback OFF; no uiKit override. INV-204 */
@@ -1799,6 +1878,8 @@ exports.useDerivedConnectStatus = useDerivedConnectStatus;
 exports.useDerivedDisconnect = useDerivedDisconnect;
 exports.useDerivedSwitchChainStatus = useDerivedSwitchChainStatus;
 exports.useNameResolutionContext = useNameResolutionContext;
+exports.useNetworkNameResolver = useNetworkNameResolver;
+exports.useNetworkResolveAddress = useNetworkResolveAddress;
 exports.useResolveAddress = useResolveAddress;
 exports.useResolveName = useResolveName;
 exports.useResolveRuntime = useResolveRuntime;