@openzeppelin/ui-components 1.3.0 → 1.4.0

package/dist/index.cjs

@@ -115,11 +115,58 @@ const AccordionContent = react.forwardRef(({ className, children, variant: varia
 AccordionContent.displayName = "AccordionContent";
 
 //#endregion
-//#region src/components/ui/address-display.tsx
-/** Displays a blockchain address with optional truncation, copy button, and explorer link. */
-function AddressDisplay({ address, truncate = true, startChars = 6, endChars = 4, showCopyButton = false, showCopyButtonOnHover = false, explorerUrl, className, ...props }) {
+//#region src/components/ui/address-display/context.ts
+/**
+* @internal Shared context instance consumed by both AddressDisplay and
+* AddressLabelProvider. Kept in its own file so component files export
+* only components (required by React Fast Refresh).
+*/
+const AddressLabelContext = (0, react.createContext)(null);
+
+//#endregion
+//#region src/components/ui/address-display/address-display.tsx
+/**
+* Displays a blockchain address with optional truncation, copy button,
+* explorer link, and human-readable label.
+*
+* Labels are resolved in priority order:
+* 1. Explicit `label` prop
+* 2. `AddressLabelContext` resolver (via `AddressLabelProvider`)
+* 3. No label (renders address only, identical to previous behavior)
+*
+* Pass `disableLabel` to suppress context-based resolution (e.g. when the
+* surrounding UI already shows a name, such as a contract selector).
+*
+* @example
+* ```tsx
+* // Basic usage (unchanged)
+* <AddressDisplay address="0x742d35Cc..." showCopyButton />
+*
+* // Explicit label
+* <AddressDisplay address="0x742d35Cc..." label="Treasury" />
+*
+* // Auto-resolved via context (no changes needed at call site)
+* <AddressLabelProvider resolveLabel={myResolver}>
+*   <AddressDisplay address="0x742d35Cc..." />
+* </AddressLabelProvider>
+*
+* // Suppress label resolution for a specific instance
+* <AddressDisplay address="0x742d35Cc..." disableLabel />
+* ```
+*/
+function AddressDisplay({ address, truncate = true, startChars = 6, endChars = 4, showCopyButton = false, showCopyButtonOnHover = false, explorerUrl, label: labelProp, onLabelEdit: onLabelEditProp, networkId, disableLabel = false, className, ...props }) {
 	const [copied, setCopied] = react.useState(false);
 	const copyTimeoutRef = react.useRef(null);
+	const resolver = react.useContext(AddressLabelContext);
+	const resolvedLabel = disableLabel ? void 0 : labelProp ?? resolver?.resolveLabel(address, networkId);
+	const contextEditHandler = react.useCallback(() => {
+		resolver?.onEditLabel?.(address, networkId);
+	}, [
+		resolver,
+		address,
+		networkId
+	]);
+	const editHandler = disableLabel ? void 0 : onLabelEditProp ?? (resolver?.onEditLabel ? contextEditHandler : void 0);
 	const displayAddress = truncate ? (0, _openzeppelin_ui_utils.truncateMiddle)(address, startChars, endChars) : address;
 	const handleCopy = (e) => {
 		e.stopPropagation();
@@ -136,11 +183,7 @@ function AddressDisplay({ address, truncate = true, startChars = 6, endChars = 4
 			if (copyTimeoutRef.current) window.clearTimeout(copyTimeoutRef.current);
 		};
 	}, []);
-	const addressContent = /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
-		/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-			className: (0, _openzeppelin_ui_utils.cn)("truncate", truncate ? "" : "break-all"),
-			children: displayAddress
-		}),
+	const actionButtons = /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 		showCopyButton && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 			type: "button",
 			onClick: handleCopy,
@@ -155,15 +198,136 @@ function AddressDisplay({ address, truncate = true, startChars = 6, endChars = 4
 			className: "ml-1.5 shrink-0 text-slate-500 transition-colors hover:text-slate-700",
 			"aria-label": "View in explorer",
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ExternalLink, { className: "h-3.5 w-3.5" })
+		}),
+		editHandler && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+			type: "button",
+			onClick: (e) => {
+				e.stopPropagation();
+				editHandler();
+			},
+			className: "ml-0 w-0 shrink-0 overflow-hidden text-slate-500 opacity-0 transition-all duration-150 hover:text-slate-700 group-hover:ml-1.5 group-hover:w-3.5 group-hover:opacity-100 focus:ml-1.5 focus:w-3.5 focus:opacity-100",
+			"aria-label": "Edit label",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Pencil, { className: "h-3.5 w-3.5" })
 		})
 	] });
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+	if (resolvedLabel) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("group inline-flex max-w-full flex-col rounded-md bg-slate-100 px-2 py-1", "text-xs text-slate-700", className),
+		...props,
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: "truncate font-sans font-medium text-slate-900 leading-snug",
+			children: resolvedLabel
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "flex items-center font-mono text-[10px] text-slate-400 leading-snug",
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: (0, _openzeppelin_ui_utils.cn)("truncate", truncate ? "" : "break-all"),
+				children: displayAddress
+			}), actionButtons]
+		})]
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: (0, _openzeppelin_ui_utils.cn)("group inline-flex max-w-full items-center rounded-md bg-slate-100 px-2 py-1", "text-xs font-mono text-slate-700", className),
 		...props,
-		children: addressContent
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: (0, _openzeppelin_ui_utils.cn)("truncate", truncate ? "" : "break-all"),
+			children: displayAddress
+		}), actionButtons]
+	});
+}
+
+//#endregion
+//#region src/components/ui/address-display/address-label-context.tsx
+/**
+* Address Label Context
+*
+* Provides a React context for resolving human-readable labels for blockchain
+* addresses. When an `AddressLabelProvider` is mounted, every `AddressDisplay`
+* in the subtree automatically resolves and renders labels without any
+* call-site changes.
+*
+* @example
+* ```tsx
+* import { AddressLabelProvider } from '@openzeppelin/ui-components';
+*
+* function App() {
+*   const resolver = useAliasLabelResolver(db);
+*   return (
+*     <AddressLabelProvider {...resolver}>
+*       <MyApp />
+*     </AddressLabelProvider>
+*   );
+* }
+* ```
+*/
+/**
+* Provides address label resolution to all `AddressDisplay` instances in the
+* subtree. Wrap your application (or a subsection) with this provider and
+* supply a `resolveLabel` function.
+*
+* @param props - Resolver functions and children
+*
+* @example
+* ```tsx
+* <AddressLabelProvider
+*   resolveLabel={(addr) => addressBook.get(addr)}
+*   onEditLabel={(addr) => openEditor(addr)}
+* >
+*   <App />
+* </AddressLabelProvider>
+* ```
+*/
+function AddressLabelProvider({ children, resolveLabel, onEditLabel }) {
+	const value = react.useMemo(() => ({
+		resolveLabel,
+		onEditLabel
+	}), [resolveLabel, onEditLabel]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AddressLabelContext.Provider, {
+		value,
+		children
 	});
 }
 
+//#endregion
+//#region src/components/ui/address-display/use-address-label.ts
+/**
+* Convenience hook for resolving an address label from the nearest
+* `AddressLabelProvider`.
+*
+* Kept in its own file so that `address-label-context.tsx` exports only
+* components (required by React Fast Refresh).
+*/
+/**
+* Convenience hook that resolves a label for a specific address using the
+* nearest `AddressLabelProvider`. Returns `undefined` values when no provider
+* is mounted.
+*
+* @param address - The blockchain address to resolve
+* @param networkId - Optional network identifier for network-specific aliases
+* @returns Resolved label and edit handler for the address
+*
+* @example
+* ```tsx
+* function MyAddress({ address }: { address: string }) {
+*   const { label, onEdit } = useAddressLabel(address, 'ethereum-mainnet');
+*   return <span>{label ?? address}</span>;
+* }
+* ```
+*/
+function useAddressLabel(address, networkId) {
+	const resolver = react.useContext(AddressLabelContext);
+	const label = resolver?.resolveLabel(address, networkId);
+	const onEdit = react.useCallback(() => {
+		resolver?.onEditLabel?.(address, networkId);
+	}, [
+		resolver,
+		address,
+		networkId
+	]);
+	return {
+		label,
+		onEdit: resolver?.onEditLabel ? onEdit : void 0
+	};
+}
+
 //#endregion
 //#region src/components/ui/alert.tsx
 const alertVariants = (0, class_variance_authority.cva)("relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground", {
@@ -1097,10 +1261,15 @@ function NetworkIcon({ network, className, size = 16, variant = "branded" }) {
 
 //#endregion
 //#region src/components/ui/network-selector.tsx
-/** Searchable dropdown selector for blockchain networks with optional grouping. */
-function NetworkSelector({ networks, selectedNetwork, onSelectNetwork, getNetworkLabel, getNetworkIcon, getNetworkType, getNetworkId, groupByEcosystem = false, getEcosystem, filterNetwork, className, placeholder = "Select Network" }) {
+/** Searchable dropdown selector for blockchain networks with optional grouping and multi-select. */
+function NetworkSelector({ networks, getNetworkLabel, getNetworkIcon, getNetworkType, getNetworkId, groupByEcosystem = false, getEcosystem, filterNetwork, className, placeholder = "Select Network", ...modeProps }) {
 	const [open, setOpen] = react.useState(false);
 	const [searchQuery, setSearchQuery] = react.useState("");
+	const isMultiple = modeProps.multiple === true;
+	const selectedNetworkIds = isMultiple ? modeProps.selectedNetworkIds : void 0;
+	const onSelectionChange = isMultiple ? modeProps.onSelectionChange : void 0;
+	const selectedNetwork = !isMultiple ? modeProps.selectedNetwork : void 0;
+	const onSelectNetwork = !isMultiple ? modeProps.onSelectNetwork : void 0;
 	const filteredNetworks = react.useMemo(() => {
 		if (!searchQuery) return networks;
 		if (filterNetwork) return networks.filter((n) => filterNetwork(n, searchQuery));
@@ -1124,34 +1293,79 @@ function NetworkSelector({ networks, selectedNetwork, onSelectNetwork, getNetwor
 		groupByEcosystem,
 		getEcosystem
 	]);
+	const isSelected = react.useCallback((network) => {
+		if (isMultiple && selectedNetworkIds) return selectedNetworkIds.includes(getNetworkId(network));
+		return selectedNetwork ? getNetworkId(selectedNetwork) === getNetworkId(network) : false;
+	}, [
+		isMultiple,
+		selectedNetworkIds,
+		selectedNetwork,
+		getNetworkId
+	]);
+	const handleSelect = react.useCallback((network) => {
+		if (isMultiple && selectedNetworkIds && onSelectionChange) {
+			const id = getNetworkId(network);
+			onSelectionChange(selectedNetworkIds.includes(id) ? selectedNetworkIds.filter((x) => x !== id) : [...selectedNetworkIds, id]);
+		} else if (onSelectNetwork) {
+			onSelectNetwork(network);
+			setOpen(false);
+		}
+	}, [
+		isMultiple,
+		selectedNetworkIds,
+		onSelectionChange,
+		onSelectNetwork,
+		getNetworkId
+	]);
+	const handleClearAll = react.useCallback(() => {
+		if (isMultiple && onSelectionChange) onSelectionChange([]);
+	}, [isMultiple, onSelectionChange]);
+	const selectedCount = selectedNetworkIds?.length ?? 0;
+	const renderTrigger = isMultiple ? modeProps.renderTrigger : void 0;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(DropdownMenu, {
 		open,
 		onOpenChange: setOpen,
 		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuTrigger, {
 			asChild: true,
-			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Button, {
-				variant: "outline",
-				role: "combobox",
-				"aria-expanded": open,
-				className: (0, _openzeppelin_ui_utils.cn)("w-full justify-between", className),
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-					className: "flex items-center gap-2 truncate",
-					children: selectedNetwork ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
-						getNetworkIcon?.(selectedNetwork),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-							className: "truncate",
-							children: getNetworkLabel(selectedNetwork)
-						}),
-						getNetworkType && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-							className: "shrink-0 rounded-sm bg-muted px-1.5 py-0.5 text-[10px] font-medium uppercase text-muted-foreground",
-							children: getNetworkType(selectedNetwork)
+			children: (() => {
+				if (isMultiple && renderTrigger) return renderTrigger({
+					selectedCount,
+					open
+				});
+				if (isMultiple) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Button, {
+					variant: "outline",
+					role: "combobox",
+					"aria-expanded": open,
+					className: (0, _openzeppelin_ui_utils.cn)("w-full justify-between", className),
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "truncate text-muted-foreground",
+						children: selectedCount > 0 ? `${selectedCount} network${selectedCount > 1 ? "s" : ""} selected` : placeholder
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronDown, { className: "ml-2 h-4 w-4 shrink-0 opacity-50" })]
+				});
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Button, {
+					variant: "outline",
+					role: "combobox",
+					"aria-expanded": open,
+					className: (0, _openzeppelin_ui_utils.cn)("w-full justify-between", className),
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "flex items-center gap-2 truncate",
+						children: selectedNetwork ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+							getNetworkIcon?.(selectedNetwork),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "truncate",
+								children: getNetworkLabel(selectedNetwork)
+							}),
+							getNetworkType && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "shrink-0 rounded-sm bg-muted px-1.5 py-0.5 text-[10px] font-medium uppercase text-muted-foreground",
+								children: getNetworkType(selectedNetwork)
+							})
+						] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "text-muted-foreground",
+							children: placeholder
 						})
-					] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-						className: "text-muted-foreground",
-						children: placeholder
-					})
-				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronDown, { className: "ml-2 h-4 w-4 shrink-0 opacity-50" })]
-			})
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronDown, { className: "ml-2 h-4 w-4 shrink-0 opacity-50" })]
+				});
+			})()
 		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(DropdownMenuContent, {
 			className: "w-[--radix-dropdown-menu-trigger-width] min-w-[240px] p-0",
 			align: "start",
@@ -1167,9 +1381,19 @@ function NetworkSelector({ networks, selectedNetwork, onSelectNetwork, getNetwor
 					className: "h-9 w-full border-0 bg-transparent p-0 placeholder:text-muted-foreground focus-visible:ring-0 focus-visible:ring-offset-0",
 					"aria-label": "Search networks"
 				})]
-			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "max-h-[300px] overflow-y-auto p-1",
-				children: Object.entries(groupedNetworks).length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				children: [isMultiple && selectedCount > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "flex items-center justify-between px-2 py-1.5",
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+						className: "text-xs font-medium text-muted-foreground",
+						children: [selectedCount, " selected"]
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						onClick: handleClearAll,
+						className: "text-xs text-muted-foreground hover:text-foreground",
+						children: "Clear all"
+					})]
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuSeparator, {})] }), Object.entries(groupedNetworks).length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 					className: "py-6 text-center text-sm text-muted-foreground",
 					children: "No network found."
 				}) : Object.entries(groupedNetworks).map(([group, groupNetworks], index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.Fragment, { children: [
@@ -1178,12 +1402,16 @@ function NetworkSelector({ networks, selectedNetwork, onSelectNetwork, getNetwor
 						children: group
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuGroup, { children: groupNetworks.map((network) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(DropdownMenuItem, {
-						onSelect: () => {
-							onSelectNetwork(network);
-							setOpen(false);
+						onSelect: (e) => {
+							if (isMultiple) e.preventDefault();
+							handleSelect(network);
 						},
 						className: "gap-2",
 						children: [
+							isMultiple ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "flex h-4 w-4 shrink-0 items-center justify-center rounded-sm border border-primary",
+								children: isSelected(network) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Check, { className: "h-3 w-3" })
+							}) : null,
 							getNetworkIcon?.(network),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 								className: "flex flex-1 items-center gap-2 min-w-0",
@@ -1195,11 +1423,11 @@ function NetworkSelector({ networks, selectedNetwork, onSelectNetwork, getNetwor
 									children: getNetworkType(network)
 								})]
 							}),
-							selectedNetwork && getNetworkId(selectedNetwork) === getNetworkId(network) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Check, { className: "h-4 w-4 opacity-100" })
+							!isMultiple && isSelected(network) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Check, { className: "h-4 w-4 opacity-100" })
 						]
 					}, getNetworkId(network))) }),
 					index < Object.keys(groupedNetworks).length - 1 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuSeparator, {})
-				] }, group))
+				] }, group))]
 			})]
 		})]
 	});
@@ -1232,6 +1460,32 @@ function NetworkStatusBadge({ network, className }) {
 	});
 }
 
+//#endregion
+//#region src/components/ui/overflow-menu.tsx
+/** Compact "..." dropdown menu for secondary actions. */
+function OverflowMenu({ items, align = "end", className, "aria-label": ariaLabel = "More actions" }) {
+	if (items.length === 0) return null;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(DropdownMenu, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuTrigger, {
+		asChild: true,
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+			variant: "ghost",
+			size: "icon",
+			className: (0, _openzeppelin_ui_utils.cn)("h-8 w-8", className),
+			"aria-label": ariaLabel,
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.MoreHorizontal, { className: "h-4 w-4" })
+		})
+	}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuContent, {
+		align,
+		className: "min-w-[140px]",
+		children: items.map((item, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.Fragment, { children: [item.destructive && index > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DropdownMenuSeparator, {}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(DropdownMenuItem, {
+			onClick: item.onSelect,
+			disabled: item.disabled,
+			className: (0, _openzeppelin_ui_utils.cn)(item.destructive && "text-destructive focus:text-destructive"),
+			children: [item.icon, item.label]
+		})] }, item.id))
+	})] });
+}
+
 //#endregion
 //#region src/components/ui/progress.tsx
 const Progress = react.forwardRef(({ className, value, ...props }, ref) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_radix_ui_react_progress.Root, {
@@ -1601,6 +1855,15 @@ function ViewContractStateButton({ contractAddress, onToggle }) {
 	});
 }
 
+//#endregion
+//#region src/components/fields/address-suggestion/context.ts
+/**
+* @internal Shared context instance consumed by both AddressField and
+* AddressSuggestionProvider. Kept in its own file so component files export
+* only components (required by React Fast Refresh).
+*/
+const AddressSuggestionContext = (0, react.createContext)(null);
+
 //#endregion
 //#region src/components/fields/utils/accessibility.ts
 /**
@@ -1792,6 +2055,8 @@ function getWidthClasses(width) {
 
 //#endregion
 //#region src/components/fields/AddressField.tsx
+const DEBOUNCE_MS = 200;
+const MAX_SUGGESTIONS = 5;
 /**
 * Address input field component specifically designed for blockchain addresses via React Hook Form integration.
 *
@@ -1809,11 +2074,82 @@ function getWidthClasses(width) {
 * - Chain-agnostic design (validation handled by adapters)
 * - Full accessibility support with ARIA attributes
 * - Keyboard navigation
+*
+* Autocomplete suggestions can be provided in two ways:
+*
+* 1. **Context-based (zero-config)**: Mount an `AddressSuggestionProvider` in the
+*    component tree. Every `AddressField` below it automatically resolves suggestions.
+*
+* 2. **Prop-based (explicit)**: Pass `suggestions` directly. This overrides context.
+*    Pass `suggestions={false}` to opt out when a provider is mounted.
+*
+* The suggestion dropdown includes built-in debouncing, keyboard navigation (Arrow keys,
+* Enter, Escape), click-outside dismissal, and ARIA listbox semantics.
 */
-function AddressField({ id, label, placeholder, helperText, control, name, width = "full", validation, adapter, readOnly }) {
+function AddressField({ id, label, placeholder, helperText, control, name, width = "full", validation, adapter, readOnly, suggestions: suggestionsProp, onSuggestionSelect }) {
 	const isRequired = !!validation?.required;
 	const errorId = `${id}-error`;
 	const descriptionId = `${id}-description`;
+	const contextResolver = (0, react.useContext)(AddressSuggestionContext);
+	const containerRef = (0, react.useRef)(null);
+	const lastSetValueRef = (0, react.useRef)("");
+	const [inputValue, setInputValue] = (0, react.useState)("");
+	const [debouncedQuery, setDebouncedQuery] = (0, react.useState)("");
+	const [showSuggestions, setShowSuggestions] = (0, react.useState)(false);
+	const [highlightedIndex, setHighlightedIndex] = (0, react.useState)(-1);
+	const watchedFieldValue = (0, react_hook_form.useWatch)({
+		control,
+		name
+	});
+	(0, react.useEffect)(() => {
+		const currentFieldValue = watchedFieldValue ?? "";
+		if (currentFieldValue !== lastSetValueRef.current) {
+			lastSetValueRef.current = currentFieldValue;
+			setInputValue(currentFieldValue);
+		}
+	}, [watchedFieldValue]);
+	(0, react.useEffect)(() => {
+		if (!inputValue.trim()) {
+			setDebouncedQuery("");
+			return;
+		}
+		const timer = setTimeout(() => setDebouncedQuery(inputValue), DEBOUNCE_MS);
+		return () => clearTimeout(timer);
+	}, [inputValue]);
+	const suggestionsDisabled = suggestionsProp === false;
+	const resolvedSuggestions = (0, react.useMemo)(() => {
+		if (suggestionsDisabled) return [];
+		if (Array.isArray(suggestionsProp)) return suggestionsProp;
+		if (!contextResolver || !debouncedQuery.trim()) return [];
+		return contextResolver.resolveSuggestions(debouncedQuery).slice(0, MAX_SUGGESTIONS);
+	}, [
+		suggestionsDisabled,
+		suggestionsProp,
+		contextResolver,
+		debouncedQuery
+	]);
+	const hasSuggestions = showSuggestions && resolvedSuggestions.length > 0;
+	(0, react.useEffect)(() => {
+		let active = true;
+		const handleClickOutside = (e) => {
+			if (active && containerRef.current && !containerRef.current.contains(e.target)) setShowSuggestions(false);
+		};
+		document.addEventListener("mousedown", handleClickOutside);
+		return () => {
+			active = false;
+			document.removeEventListener("mousedown", handleClickOutside);
+		};
+	}, []);
+	const handleSuggestionKeyDown = (0, react.useCallback)((e) => {
+		if (!hasSuggestions) return;
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			setHighlightedIndex((prev) => prev < resolvedSuggestions.length - 1 ? prev + 1 : 0);
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			setHighlightedIndex((prev) => prev > 0 ? prev - 1 : resolvedSuggestions.length - 1);
+		}
+	}, [hasSuggestions, resolvedSuggestions.length]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: `flex flex-col gap-2 ${width === "full" ? "w-full" : width === "half" ? "w-1/2" : "w-1/3"}`,
 		children: [label && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Label, {
@@ -1847,9 +2183,32 @@ function AddressField({ id, label, placeholder, helperText, control, name, width
 				const handleInputChange = (e) => {
 					const value = e.target.value;
 					field.onChange(value);
+					lastSetValueRef.current = value;
+					setInputValue(value);
+					setShowSuggestions(value.length > 0);
+					setHighlightedIndex(-1);
+				};
+				const applySuggestion = (suggestion) => {
+					field.onChange(suggestion.value);
+					onSuggestionSelect?.(suggestion);
+					lastSetValueRef.current = suggestion.value;
+					setInputValue(suggestion.value);
+					setShowSuggestions(false);
+					setHighlightedIndex(-1);
 				};
 				const handleKeyDown = (e) => {
-					if (e.key === "Escape") handleEscapeKey(field.onChange, field.value)(e);
+					if (hasSuggestions && e.key === "Enter" && highlightedIndex >= 0) {
+						e.preventDefault();
+						applySuggestion(resolvedSuggestions[highlightedIndex]);
+						return;
+					}
+					if (e.key === "Escape") {
+						if (hasSuggestions) {
+							setShowSuggestions(false);
+							return;
+						}
+						handleEscapeKey(field.onChange, field.value)(e);
+					}
 				};
 				const accessibilityProps = getAccessibilityProps({
 					id,
@@ -1858,18 +2217,50 @@ function AddressField({ id, label, placeholder, helperText, control, name, width
 					hasHelperText: !!helperText
 				});
 				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Input, {
-						...field,
-						id,
-						placeholder: placeholder || "0x...",
-						className: validationClasses,
-						onChange: handleInputChange,
-						onKeyDown: handleKeyDown,
-						"data-slot": "input",
-						value: field.value ?? "",
-						...accessibilityProps,
-						"aria-describedby": `${helperText ? descriptionId : ""} ${hasError ? errorId : ""}`,
-						disabled: readOnly
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						ref: containerRef,
+						className: "relative",
+						onKeyDown: handleSuggestionKeyDown,
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Input, {
+							...field,
+							id,
+							placeholder: placeholder || "0x...",
+							className: validationClasses,
+							onChange: handleInputChange,
+							onKeyDown: handleKeyDown,
+							"data-slot": "input",
+							value: field.value ?? "",
+							...accessibilityProps,
+							"aria-describedby": `${helperText ? descriptionId : ""} ${hasError ? errorId : ""}`,
+							"aria-expanded": hasSuggestions,
+							"aria-autocomplete": suggestionsDisabled ? void 0 : "list",
+							"aria-controls": hasSuggestions ? `${id}-suggestions` : void 0,
+							"aria-activedescendant": hasSuggestions && highlightedIndex >= 0 ? `${id}-suggestion-${highlightedIndex}` : void 0,
+							disabled: readOnly
+						}), hasSuggestions && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							id: `${id}-suggestions`,
+							className: (0, _openzeppelin_ui_utils.cn)("absolute z-50 mt-1 w-full rounded-md border border-border bg-popover shadow-md", "max-h-48 overflow-auto"),
+							role: "listbox",
+							children: resolvedSuggestions.map((s, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+								id: `${id}-suggestion-${i}`,
+								type: "button",
+								role: "option",
+								"aria-selected": i === highlightedIndex,
+								className: (0, _openzeppelin_ui_utils.cn)("flex w-full flex-col px-3 py-2 text-left text-sm", "hover:bg-accent", i === highlightedIndex && "bg-accent"),
+								onMouseDown: (e) => {
+									e.preventDefault();
+									applySuggestion(s);
+								},
+								onMouseEnter: () => setHighlightedIndex(i),
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "font-medium",
+									children: s.label
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "truncate font-mono text-xs text-muted-foreground",
+									children: s.value
+								})]
+							}, `${s.value}-${s.description ?? i}`))
+						})]
 					}),
 					helperText && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 						id: descriptionId,
@@ -1888,6 +2279,90 @@ function AddressField({ id, label, placeholder, helperText, control, name, width
 }
 AddressField.displayName = "AddressField";
 
+//#endregion
+//#region src/components/fields/address-suggestion/address-suggestion-context.tsx
+/**
+* Address Suggestion Context
+*
+* Provides a React context for resolving address autocomplete suggestions.
+* When an `AddressSuggestionProvider` is mounted, every `AddressField`
+* in the subtree automatically renders a suggestion dropdown as the user types.
+*
+* @example
+* ```tsx
+* import { AddressSuggestionProvider } from '@openzeppelin/ui-components';
+* import { useAliasSuggestionResolver } from '@openzeppelin/ui-storage';
+*
+* function App() {
+*   const resolver = useAliasSuggestionResolver(db);
+*   return (
+*     <AddressSuggestionProvider {...resolver}>
+*       <MyApp />
+*     </AddressSuggestionProvider>
+*   );
+* }
+* ```
+*/
+/**
+* Provides address suggestion resolution to all `AddressField` instances in the
+* subtree. Wrap your application (or a subsection) with this provider and
+* supply a `resolveSuggestions` function.
+*
+* @param props - Resolver function and children
+*
+* @example
+* ```tsx
+* <AddressSuggestionProvider
+*   resolveSuggestions={(query, networkId) => filterAliases(query, networkId)}
+* >
+*   <App />
+* </AddressSuggestionProvider>
+* ```
+*/
+function AddressSuggestionProvider({ children, resolveSuggestions }) {
+	const value = react.useMemo(() => ({ resolveSuggestions }), [resolveSuggestions]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AddressSuggestionContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+//#region src/components/fields/address-suggestion/useAddressSuggestions.ts
+/**
+* Convenience hook that resolves suggestions for a query string using the
+* nearest `AddressSuggestionProvider`. Returns an empty array when no provider
+* is mounted or when the query is empty.
+*
+* @param query - Current input value to match against
+* @param networkId - Optional network identifier for scoping results
+* @returns Object containing the resolved suggestions array
+*
+* @example
+* ```tsx
+* function MyField({ query }: { query: string }) {
+*   const { suggestions } = useAddressSuggestions(query, 'ethereum-mainnet');
+*   return (
+*     <ul>
+*       {suggestions.map(s => <li key={s.value}>{s.label}</li>)}
+*     </ul>
+*   );
+* }
+* ```
+*/
+/** Resolves address suggestions from the nearest `AddressSuggestionProvider`. */
+function useAddressSuggestions(query, networkId) {
+	const resolver = react.useContext(AddressSuggestionContext);
+	return { suggestions: react.useMemo(() => {
+		if (!resolver || !query.trim()) return [];
+		return resolver.resolveSuggestions(query, networkId);
+	}, [
+		resolver,
+		query,
+		networkId
+	]) };
+}
+
 //#endregion
 //#region src/components/fields/AmountField.tsx
 /**
@@ -5263,6 +5738,8 @@ exports.AccordionItem = AccordionItem;
 exports.AccordionTrigger = AccordionTrigger;
 exports.AddressDisplay = AddressDisplay;
 exports.AddressField = AddressField;
+exports.AddressLabelProvider = AddressLabelProvider;
+exports.AddressSuggestionProvider = AddressSuggestionProvider;
 exports.Alert = Alert;
 exports.AlertDescription = AlertDescription;
 exports.AlertTitle = AlertTitle;
@@ -5342,6 +5819,7 @@ exports.NetworkServiceErrorBanner = NetworkServiceErrorBanner;
 exports.NetworkStatusBadge = NetworkStatusBadge;
 exports.NumberField = NumberField;
 exports.ObjectField = ObjectField;
+exports.OverflowMenu = OverflowMenu;
 exports.PasswordField = PasswordField;
 exports.Popover = Popover;
 exports.PopoverAnchor = PopoverAnchor;
@@ -5399,6 +5877,8 @@ exports.handleToggleKeys = handleToggleKeys;
 exports.handleValidationError = require_ErrorMessage.handleValidationError;
 exports.hasFieldError = require_ErrorMessage.hasFieldError;
 exports.isDuplicateMapKey = require_ErrorMessage.isDuplicateMapKey;
+exports.useAddressLabel = useAddressLabel;
+exports.useAddressSuggestions = useAddressSuggestions;
 exports.useDuplicateKeyIndexes = useDuplicateKeyIndexes;
 exports.useMapFieldSync = useMapFieldSync;
 exports.useNetworkErrorAwareAdapter = useNetworkErrorAwareAdapter;