@openzeppelin/ui-react 3.0.0 → 3.1.0

package/dist/index.mjs

@@ -1,10 +1,11 @@
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { AnalyticsService, cn, isRecordWithProperties, logger } from "@openzeppelin/ui-utils";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { QueryClient, useQuery } from "@tanstack/react-query";
 import { Button } from "@openzeppelin/ui-components";
 
 //#region src/version.ts
-const VERSION = "3.0.0";
+const VERSION = "3.1.0";
 
 //#endregion
 //#region src/hooks/AdapterContext.tsx
@@ -244,12 +245,12 @@ const WALLET_STATE_CONTEXT_KEY = Symbol.for("@openzeppelin/ui-react/WalletStateC
 * 4. For React contexts specifically, having the same context object is what matters,
 *    and this pattern guarantees that after initialization
 */
-function getOrCreateSharedContext() {
+function getOrCreateSharedContext$1() {
 	const global = globalThis;
 	if (!global[WALLET_STATE_CONTEXT_KEY]) global[WALLET_STATE_CONTEXT_KEY] = createContext(void 0);
 	return global[WALLET_STATE_CONTEXT_KEY];
 }
-const WalletStateContext = getOrCreateSharedContext();
+const WalletStateContext = getOrCreateSharedContext$1();
 /**
 * Hook to access wallet state from WalletStateProvider.
 * @throws Error if used outside of WalletStateProvider
@@ -877,6 +878,536 @@ function useWalletReconnectionHandler(selectedNetworkConfigId, selectedCapabilit
 	]);
 }
 
+//#endregion
+//#region src/hooks/nameResolution/resolutionConfig.ts
+/**
+* Default resolution config. Values sit within the spec's "seconds-to-minutes"
+* caching guidance; forward debounce is 300ms (typed char-by-char), reverse is 0.
+*/
+const DEFAULT_CONFIG = {
+	staleTimeMs: 6e4,
+	gcTimeMs: 3e5,
+	forwardDebounceMs: 300,
+	reverseDebounceMs: 0,
+	transientRetryCount: 2
+};
+/** Stable prefix for every resolution cache key — namespaces this package's keys. */
+const RESOLUTION_KEY_PREFIX = "oz-name-resolution";
+/**
+* Build a network-scoped, namespace-separated cache key (INV-40). A name resolves
+* differently per network and provenance can be chain-scoped, so `networkId` is
+* part of the key; `namespace` keeps forward and reverse lookups disjoint.
+*
+* @param namespace       - `'name'` (forward) or `'addr'` (reverse).
+* @param networkId       - Active network id (`''` when no network is selected).
+* @param normalizedInput - Trimmed + lowercased input (INV-26).
+* @returns A readonly tuple suitable for a TanStack Query `queryKey`.
+*/
+function buildResolutionKey(namespace, networkId, normalizedInput) {
+	return [
+		RESOLUTION_KEY_PREFIX,
+		namespace,
+		networkId,
+		normalizedInput
+	];
+}
+/**
+* Whether a resolution error is transient (worth retrying) versus a definitive,
+* stable answer (INV-47). Exhaustive over SF-1's closed error union with no
+* `default`: adding a new error code to `@openzeppelin/ui-types` will fail to
+* compile here until it is classified — deliberately coupling SF-2 to SF-1 INV-7.
+*
+* @param error - A typed {@link NameResolutionError}.
+* @returns `true` for transient failures (timeout / gateway / adapter), `false`
+*   for definitive negatives and unsupported-network answers.
+*/
+function isTransientError(error) {
+	switch (error.code) {
+		case "RESOLUTION_TIMEOUT":
+		case "EXTERNAL_GATEWAY_ERROR":
+		case "ADAPTER_ERROR": return true;
+		case "NAME_NOT_FOUND":
+		case "ADDRESS_NOT_FOUND":
+		case "UNSUPPORTED_NAME":
+		case "UNSUPPORTED_NETWORK": return false;
+	}
+}
+/**
+* Construct a QueryClient tuned for name resolution: ambient refetch triggers are
+* disabled at the client level (INV-41) so a resolved value never silently
+* changes under the user on window focus or network reconnect.
+*/
+function createResolutionQueryClient() {
+	return new QueryClient({ defaultOptions: { queries: {
+		refetchOnWindowFocus: false,
+		refetchOnReconnect: false
+	} } });
+}
+/**
+* Process-global key for the default resolution QueryClient. Uses `Symbol.for`
+* so every duplicated module instance (Vite pre-bundling, npm-installed adapters)
+* shares ONE client — the same cross-bundle-singleton pattern as
+* `WalletStateContext`. This is what makes the cache shared with zero wiring
+* (SC-001) and enables cross-instance dedup / warm-cache reuse (INV-33 / INV-37 / INV-48).
+*/
+const DEFAULT_CLIENT_KEY = Symbol.for("@openzeppelin/ui-react/NameResolutionQueryClient");
+/**
+* Lazily create (exactly once) and return the process-global resolution
+* QueryClient used when no `NameResolutionProvider` is mounted (INV-48).
+*
+* @returns The shared default resolution QueryClient (stable across calls).
+*/
+function getDefaultResolutionQueryClient() {
+	const globalScope = globalThis;
+	if (!globalScope[DEFAULT_CLIENT_KEY]) globalScope[DEFAULT_CLIENT_KEY] = createResolutionQueryClient();
+	return globalScope[DEFAULT_CLIENT_KEY];
+}
+
+//#endregion
+//#region src/hooks/nameResolution/NameResolutionContext.ts
+/**
+* Process-global key for the context object. Uses `Symbol.for` so all duplicated
+* module instances share ONE React context — the same cross-bundle-singleton
+* pattern as `WalletStateContext` (bundler pre-bundling / npm-installed adapters).
+*/
+const CONTEXT_KEY = Symbol.for("@openzeppelin/ui-react/NameResolutionContext");
+function getOrCreateSharedContext() {
+	const globalScope = globalThis;
+	if (!globalScope[CONTEXT_KEY]) globalScope[CONTEXT_KEY] = createContext(null);
+	return globalScope[CONTEXT_KEY];
+}
+/**
+* React context for resolution. `null` default triggers the module-singleton
+* fallback in {@link useNameResolutionContext} — no Provider is required (INV-48).
+*/
+const NameResolutionContext = getOrCreateSharedContext();
+/**
+* Stable fallback value used when no Provider is mounted. Cached per module so the
+* returned reference is referentially stable across renders (INV-38); it wraps the
+* process-global default client, so caches are still shared even across bundles.
+*/
+let fallbackValue;
+function getFallbackContextValue() {
+	if (!fallbackValue) fallbackValue = {
+		queryClient: getDefaultResolutionQueryClient(),
+		config: DEFAULT_CONFIG
+	};
+	return fallbackValue;
+}
+/**
+* Read the resolution context, falling back to the zero-wiring default (global
+* singleton client + {@link DEFAULT_CONFIG}) when no `NameResolutionProvider` is
+* mounted (INV-48). Never throws for a missing provider.
+*
+* @returns The active {@link NameResolutionContextValue}.
+*/
+function useNameResolutionContext() {
+	return useContext(NameResolutionContext) ?? getFallbackContextValue();
+}
+
+//#endregion
+//#region src/hooks/nameResolution/resolutionState.ts
+/**
+* Internal error used to bridge SF-1's `ok: false` results (and defensively-caught
+* adapter throws) into TanStack Query's thrown-error channel, carrying the typed
+* {@link NameResolutionError} through so the mapping step can surface it unchanged
+* (INV-43). Never leaks past the hook boundary.
+*/
+var ResolutionQueryError = class extends Error {
+	resolutionError;
+	/** @param resolutionError - The typed error to carry through react-query. */
+	constructor(resolutionError) {
+		super(`name resolution failed: ${resolutionError.code}`);
+		this.name = "ResolutionQueryError";
+		this.resolutionError = resolutionError;
+	}
+};
+/**
+* Convert any value from react-query's error channel into a typed, closed-union
+* {@link NameResolutionError} (INV-43). A {@link ResolutionQueryError} is
+* unwrapped verbatim; anything else (a react-query internal error) is mapped to
+* `ADAPTER_ERROR` so no untyped throw reaches a component.
+*
+* @param error - The raw `query.error` value (`unknown`).
+* @returns A typed error drawn only from SF-1's closed union.
+*/
+function toNameResolutionError(error) {
+	if (error instanceof ResolutionQueryError) return error.resolutionError;
+	return {
+		code: "ADAPTER_ERROR",
+		message: error instanceof Error ? error.message : String(error),
+		cause: error
+	};
+}
+/**
+* Map a settled query's state to exactly one non-gate {@link EngineResult} arm
+* (INV-42, INV-44). The `input` echoed here is the debounced value the query was
+* keyed on, so `data`/`error` are always paired with the input that produced them
+* (INV-24). Success without data degrades to `loading` rather than a resolved arm
+* missing its payload.
+*
+* @param input - The debounced, normalized input keying this query.
+* @param query - The settled query state.
+* @param retry - Bound `refetch` for the `error` arm (INV-34).
+* @returns The `resolved`, `error`, or `loading` arm.
+*/
+function mapSettledQuery(input, query, retry) {
+	if (query.isSuccess && query.data !== void 0) return {
+		status: "resolved",
+		input,
+		data: query.data
+	};
+	if (query.isError) return {
+		status: "error",
+		input,
+		error: toNameResolutionError(query.error),
+		retry
+	};
+	return {
+		status: "loading",
+		input
+	};
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useResolutionEngine.ts
+const LOG_SCOPE = "useResolutionEngine";
+/** No-op retry for synthesized errors that never entered the query path (INV-45). */
+const NOOP_RETRY = () => {};
+/**
+* Shared engine behind `useResolveName` / `useResolveAddress`. Owns input
+* normalization, debouncing, the `useQuery` wiring (explicit-client form), the
+* capability-absence gate, and the mapping to a direction-agnostic
+* {@link EngineResult}. Not exported from the package.
+*/
+function useResolutionEngine(params) {
+	const { input, namespace, debounceMs, enabled, shouldAttempt, getMethod } = params;
+	const walletState = useContext(WalletStateContext);
+	const activeRuntime = walletState?.activeRuntime ?? null;
+	const activeNetworkId = walletState?.activeNetworkId ?? null;
+	const isRuntimeLoading = walletState?.isRuntimeLoading ?? false;
+	const { queryClient, config } = useNameResolutionContext();
+	const trimmedLive = (input ?? "").trim();
+	const normalizedLive = trimmedLive.toLowerCase();
+	const [debouncedTrimmed, setDebouncedTrimmed] = useState(trimmedLive);
+	const seededRef = useRef(false);
+	useEffect(() => {
+		if (!seededRef.current) {
+			seededRef.current = true;
+			return;
+		}
+		if (debounceMs <= 0) {
+			setDebouncedTrimmed(trimmedLive);
+			return;
+		}
+		const timer = setTimeout(() => setDebouncedTrimmed(trimmedLive), debounceMs);
+		return () => clearTimeout(timer);
+	}, [trimmedLive, debounceMs]);
+	const effectiveTrimmed = debounceMs <= 0 ? trimmedLive : debouncedTrimmed;
+	const normalizedKey = effectiveTrimmed.toLowerCase();
+	const capability = activeRuntime?.nameResolution;
+	const networkId = activeNetworkId ?? "";
+	const method = capability ? getMethod(capability) : void 0;
+	const liveAttemptable = capability ? shouldAttempt(capability, normalizedLive) : false;
+	const keyAttemptable = capability ? shouldAttempt(capability, normalizedKey) : false;
+	const queryEnabled = enabled && trimmedLive !== "" && capability != null && method != null && normalizedKey !== "" && keyAttemptable;
+	const query = useQuery({
+		queryKey: buildResolutionKey(namespace, networkId, normalizedKey),
+		queryFn: async () => {
+			if (!method) throw new ResolutionQueryError({
+				code: "ADAPTER_ERROR",
+				message: "resolution method unexpectedly missing"
+			});
+			const adapterArg = namespace === "addr" ? effectiveTrimmed : normalizedKey;
+			let result;
+			try {
+				result = await method(adapterArg);
+			} catch (cause) {
+				logger.warn(LOG_SCOPE, "resolution method threw instead of returning ok:false", 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;
+		},
+		enabled: queryEnabled,
+		staleTime: config.staleTimeMs,
+		gcTime: config.gcTimeMs,
+		refetchOnWindowFocus: false,
+		refetchOnReconnect: false,
+		retry: (failureCount, error) => (error instanceof ResolutionQueryError ? isTransientError(error.resolutionError) : true) && failureCount < config.transientRetryCount
+	}, queryClient);
+	if (!enabled) return { status: "idle" };
+	if (trimmedLive === "") return { status: "idle" };
+	if (capability) {
+		if (!liveAttemptable) return { status: "idle" };
+		if (!method) return unsupportedNetwork(normalizedLive, networkId);
+		if (normalizedKey !== normalizedLive) return {
+			status: "debouncing",
+			input: normalizedLive
+		};
+	} else {
+		if (isRuntimeLoading) return {
+			status: "loading",
+			input: normalizedLive
+		};
+		return unsupportedNetwork(normalizedLive, networkId);
+	}
+	const retry = () => {
+		query.refetch();
+	};
+	return mapSettledQuery(normalizedKey, query, retry);
+}
+/**
+* Synthesize an `UNSUPPORTED_NETWORK` error arm without touching react-query
+* (INV-45). Drawn from SF-1's closed union so it is indistinguishable from an
+* adapter-returned `UNSUPPORTED_NETWORK`; `networkId` may be `''` (INV-49). Retry
+* is a no-op — there is no query to refetch.
+*/
+function unsupportedNetwork(input, networkId) {
+	return {
+		status: "error",
+		input,
+		error: {
+			code: "UNSUPPORTED_NETWORK",
+			networkId
+		},
+		retry: NOOP_RETRY
+	};
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useResolveName.ts
+/**
+* Forward-resolve a name to an address. Soft-reads the active runtime from
+* `WalletStateContext` (never throws when no provider is mounted — degrades to
+* idle / UNSUPPORTED_NETWORK) and calls `runtime.nameResolution?.resolveName`.
+* Debounces `name`, caches per (network, name) via the owned QueryClient, and is
+* protected against out-of-order responses (distinct inputs → distinct query keys).
+*
+* Returns a discriminated union keyed on `status`; it never throws for expected
+* failures (they surface in the `error` arm) and never pairs a name with a
+* different name's resolved address (INV-24).
+*
+* @param name    - The name to resolve. `null` / empty / a value failing the
+*   adapter's `isValidName` yields `status: 'idle'` (never `error`).
+* @param options - `debounceMs` / `enabled` overrides.
+* @returns The current {@link UseResolveNameResult}.
+*/
+function useResolveName(name, options) {
+	const { config } = useNameResolutionContext();
+	return toNameResult(useResolutionEngine({
+		input: name,
+		namespace: "name",
+		debounceMs: options?.debounceMs ?? config.forwardDebounceMs,
+		enabled: options?.enabled ?? true,
+		shouldAttempt: (cap, normalized) => cap.isValidName(normalized),
+		getMethod: (cap) => cap.resolveName
+	}));
+}
+/**
+* Remap the engine's generic `input` to `name` (INV-24: keyed off the debounced
+* input carried in the engine result, not the live prop). Exhaustive over the
+* union so a new status cannot silently fall through (INV-23 / INV-42).
+*/
+function toNameResult(engine) {
+	switch (engine.status) {
+		case "idle": return { status: "idle" };
+		case "debouncing": return {
+			status: "debouncing",
+			name: engine.input
+		};
+		case "loading": return {
+			status: "loading",
+			name: engine.input
+		};
+		case "resolved": return {
+			status: "resolved",
+			name: engine.input,
+			data: engine.data
+		};
+		case "error": return {
+			status: "error",
+			name: engine.input,
+			error: engine.error,
+			retry: engine.retry
+		};
+	}
+}
+
+//#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
+	}));
+}
+/**
+* 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) {
+	switch (engine.status) {
+		case "idle": return { status: "idle" };
+		case "debouncing":
+		case "loading": return {
+			status: "loading",
+			address: engine.input
+		};
+		case "resolved": return {
+			status: "resolved",
+			address: engine.input,
+			data: engine.data
+		};
+		case "error": return {
+			status: "error",
+			address: engine.input,
+			error: engine.error,
+			retry: engine.retry
+		};
+	}
+}
+
+//#endregion
+//#region src/hooks/nameResolution/NameResolutionProvider.tsx
+/**
+* Optional provider that overrides resolution config and/or the QueryClient for
+* its subtree. It does NOT render a `QueryClientProvider`: the client is passed
+* explicitly to `useQuery` (INV-48), so no ambient react-query provider is needed.
+*
+* Config is merged field-by-field over {@link DEFAULT_CONFIG} (INV-30), and the
+* context value is memoized so a Provider re-render does not cascade to every hook
+* (INV-38).
+*/
+function NameResolutionProvider({ children, config, queryClient }) {
+	const value = useMemo(() => ({
+		queryClient: queryClient ?? getDefaultResolutionQueryClient(),
+		config: {
+			...DEFAULT_CONFIG,
+			...config
+		}
+	}), [queryClient, config]);
+	return /* @__PURE__ */ jsx(NameResolutionContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useRuntimeNameResolver.ts
+/**
+* Stable empty resolver returned when no runtime / capability is available.
+* No methods ⇒ the consuming field treats a typed name as unsupported and
+* surfaces `UNSUPPORTED_NETWORK` (INV-119) while hex behavior stays legacy.
+*/
+const EMPTY_RESOLVER = {};
+/**
+* Project the active runtime's `NameResolutionCapability` into the injected
+* {@link NameResolver} seam consumed by `@openzeppelin/ui-components` (SF-3, D3).
+* Mounted ambiently by the renderer:
+*
+* ```tsx
+* <NameResolverProvider {...useRuntimeNameResolver()}>{form}</NameResolverProvider>
+* ```
+*
+* 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
+* resolved through the field and the same name resolved by a bare
+* `useResolveName` hit the SAME cache entry: shared cache, dedupe, and
+* 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 active runtime, or runtime without the capability → empty resolver.
+* - Capability without `resolveName` → `isValidName` only; forward unsupported.
+*
+* When the capability is present but the network itself is unsupported, the
+* adapter's `resolveName` resolves `{ ok: false, error: UNSUPPORTED_NETWORK }`
+* and that result passes through unchanged.
+*
+* @returns A referentially stable {@link NameResolver} for the active runtime.
+*/
+function useRuntimeNameResolver() {
+	const walletState = useContext(WalletStateContext);
+	const { queryClient, config } = useNameResolutionContext();
+	const capability = walletState?.activeRuntime?.nameResolution;
+	const networkId = walletState?.activeNetworkId ?? "";
+	return 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),
+							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
+		};
+	}, [
+		capability,
+		queryClient,
+		config,
+		networkId
+	]);
+}
+
 //#endregion
 //#region src/components/WalletConnectionUI.tsx
 /**
@@ -1084,5 +1615,5 @@ const NetworkSwitchManager = ({ wallet, networkCatalog, targetNetworkId, onNetwo
 };
 
 //#endregion
-export { AnalyticsContext, AnalyticsProvider, NetworkSwitchManager, RuntimeContext, RuntimeProvider, VERSION, WalletConnectionHeader, WalletConnectionUI, WalletStateContext, WalletStateProvider, useAnalytics, useDerivedAccountStatus, useDerivedChainInfo, useDerivedConnectStatus, useDerivedDisconnect, useDerivedSwitchChainStatus, useRuntimeContext, useWalletComponents, useWalletReconnectionHandler, useWalletState };
+export { AnalyticsContext, AnalyticsProvider, DEFAULT_CONFIG, NameResolutionContext, NameResolutionProvider, NetworkSwitchManager, RuntimeContext, RuntimeProvider, VERSION, WalletConnectionHeader, WalletConnectionUI, WalletStateContext, WalletStateProvider, useAnalytics, useDerivedAccountStatus, useDerivedChainInfo, useDerivedConnectStatus, useDerivedDisconnect, useDerivedSwitchChainStatus, useNameResolutionContext, useResolveAddress, useResolveName, useRuntimeContext, useRuntimeNameResolver, useWalletComponents, useWalletReconnectionHandler, useWalletState };
 //# sourceMappingURL=index.mjs.map