@openzeppelin/ui-components 1.3.0 → 1.5.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, {
@@ -1351,12 +1605,12 @@ SelectSeparator.displayName = _radix_ui_react_select.Separator.displayName;
 * Can render as a button or anchor element depending on whether href is provided.
 */
 function SidebarButton({ icon, children, onClick, size = "default", badge, disabled = false, isSelected = false, href, target, rel, className }) {
-	const commonClass = (0, _openzeppelin_ui_utils.cn)("group relative flex items-center gap-2 px-3 py-2.5 rounded-lg font-semibold text-sm transition-colors", badge ? "justify-between" : "justify-start", disabled ? "text-gray-400 cursor-not-allowed" : isSelected ? "text-[#111928] bg-neutral-100" : "text-gray-600 hover:text-gray-700 cursor-pointer hover:before:content-[\"\"] hover:before:absolute hover:before:inset-x-0 hover:before:top-1 hover:before:bottom-1 hover:before:bg-muted/80 hover:before:rounded-lg hover:before:-z-10", size === "small" ? "h-10" : "h-11", className);
+	const commonClass = (0, _openzeppelin_ui_utils.cn)("group relative flex flex-wrap items-center gap-x-2 gap-y-0.5 px-3 py-2 rounded-lg font-semibold text-sm transition-colors", badge ? "justify-between" : "justify-start", disabled ? "text-gray-400 cursor-not-allowed" : isSelected ? "text-[#111928] bg-neutral-100" : "text-gray-600 hover:text-gray-700 cursor-pointer hover:before:content-[\"\"] hover:before:absolute hover:before:inset-x-0 hover:before:top-1 hover:before:bottom-1 hover:before:bg-muted/80 hover:before:rounded-lg hover:before:-z-10", size === "small" ? "min-h-10" : "min-h-11", className);
 	const content = /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: "flex items-center gap-2",
 		children: [icon, children]
 	}), badge && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-		className: "text-xs px-2 py-1 bg-muted text-muted-foreground rounded-full font-medium",
+		className: "text-xs px-2 py-0.5 bg-muted text-muted-foreground rounded-full font-medium",
 		children: badge
 	})] });
 	if (href) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
@@ -1601,6 +1855,555 @@ function ViewContractStateButton({ contractAddress, onToggle }) {
 	});
 }
 
+//#endregion
+//#region src/components/ui/wizard/WizardStepper.tsx
+function resolveState(step, index, currentStepIndex, furthestStepIndex) {
+	if (step.status === "completed" || step.status === "skipped") return "completed";
+	if (index === currentStepIndex) return "current";
+	if (step.isInvalid && (index < currentStepIndex || index <= furthestStepIndex)) return "invalid";
+	if (index < currentStepIndex) return "completed";
+	if (index <= furthestStepIndex) return "visited";
+	return "upcoming";
+}
+function canClick(state, freeNavigation = false) {
+	if (freeNavigation) return true;
+	return state !== "upcoming";
+}
+function StepCircle({ state, index }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex size-6 shrink-0 items-center justify-center rounded-full text-xs font-semibold transition-all", state === "completed" && "bg-blue-600 text-white", state === "current" && "bg-blue-600 text-white ring-2 ring-blue-200", state === "visited" && "bg-blue-100 text-blue-600 ring-1 ring-blue-300", state === "invalid" && "bg-red-100 text-red-600 ring-1 ring-red-300", state === "upcoming" && "bg-zinc-100 text-zinc-400"),
+		children: state === "completed" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Check, { className: "size-3.5" }) : state === "visited" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Pencil, { className: "size-3" }) : state === "invalid" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.AlertCircle, { className: "size-3.5" }) : index + 1
+	});
+}
+function StepLabel({ title, state, isSkipped }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: "min-w-0 flex-1",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: (0, _openzeppelin_ui_utils.cn)("text-sm font-medium transition-colors", state === "current" && "text-blue-700", state === "completed" && "text-zinc-700", state === "visited" && "text-blue-600", state === "invalid" && "text-red-600", state === "upcoming" && "text-zinc-400"),
+			children: title
+		}), isSkipped && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: "mt-0.5 block text-[11px] text-zinc-400",
+			children: "Skipped"
+		})]
+	});
+}
+function VerticalStepper({ steps, currentStepIndex, furthestStepIndex = currentStepIndex, onStepClick, freeNavigation, className }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("nav", {
+		"aria-label": "Wizard steps",
+		className: (0, _openzeppelin_ui_utils.cn)("rounded-2xl border border-zinc-200 bg-white p-6", className),
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "flex flex-col gap-1",
+			children: steps.map((step, index) => {
+				const state = resolveState(step, index, currentStepIndex, furthestStepIndex);
+				const clickable = canClick(state, freeNavigation) && !!onStepClick;
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+					type: "button",
+					onClick: () => clickable && onStepClick?.(index),
+					disabled: !clickable,
+					className: (0, _openzeppelin_ui_utils.cn)("flex items-center gap-3 rounded-xl border border-transparent px-3 py-3 text-left transition-all duration-150", clickable ? "cursor-pointer" : "cursor-not-allowed opacity-50", state === "current" && "border-blue-200 bg-blue-50", state === "completed" && "bg-white hover:bg-gray-50", state === "visited" && "bg-white hover:bg-blue-50/50", state === "invalid" && "border-red-200 bg-red-50 hover:bg-red-100/60", state === "upcoming" && "bg-white"),
+					"aria-current": state === "current" ? "step" : void 0,
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(StepCircle, {
+						state,
+						index
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(StepLabel, {
+						title: step.title,
+						state,
+						isSkipped: step.status === "skipped"
+					})]
+				}, step.id);
+			})
+		})
+	});
+}
+function HorizontalStepper({ steps, currentStepIndex, furthestStepIndex = currentStepIndex, onStepClick, freeNavigation, className }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("nav", {
+		"aria-label": "Wizard steps",
+		className: (0, _openzeppelin_ui_utils.cn)("rounded-2xl border border-zinc-200 bg-white p-6", className),
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "flex w-full items-center",
+			children: steps.map((step, index) => {
+				const state = resolveState(step, index, currentStepIndex, furthestStepIndex);
+				const clickable = canClick(state, freeNavigation) && !!onStepClick;
+				const isLast = index === steps.length - 1;
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.default.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+					type: "button",
+					onClick: () => clickable && onStepClick?.(index),
+					disabled: !clickable,
+					className: (0, _openzeppelin_ui_utils.cn)("flex items-center gap-2 rounded-xl border border-transparent px-3 py-2 text-left transition-all duration-150", clickable ? "cursor-pointer" : "cursor-not-allowed opacity-50", state === "current" && "border-blue-200 bg-blue-50", state === "completed" && "bg-white hover:bg-gray-50", state === "visited" && "bg-white hover:bg-blue-50/50", state === "invalid" && "border-red-200 bg-red-50 hover:bg-red-100/60", state === "upcoming" && "bg-white"),
+					"aria-current": state === "current" ? "step" : void 0,
+					"aria-label": `Step ${index + 1}: ${step.title}`,
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(StepCircle, {
+						state,
+						index
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "hidden sm:block",
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(StepLabel, {
+							title: step.title,
+							state,
+							isSkipped: step.status === "skipped"
+						})
+					})]
+				}), !isLast && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: (0, _openzeppelin_ui_utils.cn)("mx-1 h-px flex-1 transition-colors sm:mx-2", index < currentStepIndex ? "bg-blue-600" : "bg-zinc-200") })] }, step.id);
+			})
+		})
+	});
+}
+/**
+* A stepper component for navigating through a series of steps.
+*
+* @param props - The props for the WizardStepper component.
+* @returns A React node representing the stepper component.
+*/
+function WizardStepper(props) {
+	const { variant = "horizontal", ...rest } = props;
+	return variant === "vertical" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(VerticalStepper, {
+		...rest,
+		variant
+	}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(HorizontalStepper, {
+		...rest,
+		variant
+	});
+}
+
+//#endregion
+//#region src/components/ui/wizard/WizardNavigation.tsx
+/**
+* A navigation component for the wizard.
+*
+* @param props - The props for the WizardNavigation component.
+* @returns A React node representing the navigation component.
+*/
+function WizardNavigation({ isFirstStep, isLastStep, canProceed = true, onPrevious, onNext, onCancel, extraActions, nextLabel = "Next", lastStepLabel = "Finish", className }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex items-center justify-between", className),
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "flex gap-2",
+			children: [onCancel && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Button, {
+				type: "button",
+				variant: "outline",
+				onClick: onCancel,
+				className: "gap-2",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.X, { className: "size-4" }), "Cancel"]
+			}), !isFirstStep && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Button, {
+				type: "button",
+				variant: "outline",
+				onClick: onPrevious,
+				className: "gap-2",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronLeft, { className: "size-4" }), "Previous"]
+			})]
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "flex gap-2",
+			children: [extraActions, /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Button, {
+				type: "button",
+				onClick: onNext,
+				disabled: !canProceed,
+				className: "gap-2",
+				children: [isLastStep ? lastStepLabel : nextLabel, !isLastStep && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronRight, { className: "size-4" })]
+			})]
+		})]
+	});
+}
+
+//#endregion
+//#region src/components/ui/wizard/hooks.ts
+/**
+* Clamp a step index into the valid range for the current wizard.
+*/
+function getSafeStepIndex(stepCount, currentStepIndex) {
+	if (stepCount === 0) return 0;
+	return Math.max(0, Math.min(currentStepIndex, stepCount - 1));
+}
+/**
+* Track the highest step reached unless a controlled value is provided.
+*/
+function useFurthestStepIndex(currentStepIndex, controlledFurthestStepIndex) {
+	const [internalFurthestStepIndex, setInternalFurthestStepIndex] = (0, react.useState)(currentStepIndex);
+	(0, react.useEffect)(() => {
+		setInternalFurthestStepIndex((prev) => Math.max(prev, currentStepIndex));
+	}, [currentStepIndex]);
+	return controlledFurthestStepIndex ?? internalFurthestStepIndex;
+}
+/**
+* Keep the scrollable wizard's active and visited step state in sync with scrolling and clicks.
+*/
+function useScrollableWizardStepTracking({ steps, currentStepIndex, onStepChange, scrollRef, sectionId, scrollPadding = SCROLL_PADDING_PX }) {
+	const safeIndex = getSafeStepIndex(steps.length, currentStepIndex);
+	const initialIndexRef = (0, react.useRef)(safeIndex);
+	const rafRef = (0, react.useRef)(null);
+	const manualSelectionIndexRef = (0, react.useRef)(null);
+	const stepsRef = (0, react.useRef)(steps);
+	const sectionIdRef = (0, react.useRef)(sectionId);
+	const onStepChangeRef = (0, react.useRef)(onStepChange);
+	const scrollPaddingRef = (0, react.useRef)(scrollPadding);
+	(0, react.useEffect)(() => {
+		stepsRef.current = steps;
+		sectionIdRef.current = sectionId;
+		onStepChangeRef.current = onStepChange;
+		scrollPaddingRef.current = scrollPadding;
+	});
+	const [activeIndex, setActiveIndex] = (0, react.useState)(initialIndexRef.current);
+	const activeIndexRef = (0, react.useRef)(initialIndexRef.current);
+	const [furthestStepIndex, setFurthestStepIndex] = (0, react.useState)(initialIndexRef.current);
+	const isMountedRef = (0, react.useRef)(false);
+	const clearManualSelection = (0, react.useCallback)(() => {
+		manualSelectionIndexRef.current = null;
+	}, []);
+	(0, react.useEffect)(() => {
+		const container = scrollRef.current;
+		if (!container) return;
+		const ownerDocument = container.ownerDocument;
+		isMountedRef.current = false;
+		let didCompleteInitialRaf = false;
+		const releaseManualSelectionOnUserScroll = () => {
+			clearManualSelection();
+		};
+		const handleKeyDown = (event) => {
+			if (isScrollableNavigationKey(event)) clearManualSelection();
+		};
+		const handleScroll = () => {
+			if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+			rafRef.current = requestAnimationFrame(() => {
+				const currentSteps = stepsRef.current;
+				const currentSectionId = sectionIdRef.current;
+				const currentOnStepChange = onStepChangeRef.current;
+				if (currentSteps.length === 0) return;
+				const manualSelectionIndex = manualSelectionIndexRef.current;
+				const naturalState = resolveScrollableActiveIndex(container, currentSteps, currentSectionId);
+				const naturalActiveIndex = naturalState.activeIndex;
+				const newActiveIndex = manualSelectionIndex ?? naturalActiveIndex;
+				const shouldCommitFurthestStepIndex = manualSelectionIndex !== null ? true : naturalState.commitFurthestStepIndex;
+				if (activeIndexRef.current !== newActiveIndex) {
+					activeIndexRef.current = newActiveIndex;
+					setActiveIndex(newActiveIndex);
+					if (isMountedRef.current) {
+						lastEmittedIndexRef.current = newActiveIndex;
+						currentOnStepChange(newActiveIndex);
+					}
+				} else setActiveIndex(newActiveIndex);
+				if (shouldCommitFurthestStepIndex) setFurthestStepIndex((prev) => Math.max(prev, newActiveIndex));
+				rafRef.current = null;
+				if (!didCompleteInitialRaf) {
+					didCompleteInitialRaf = true;
+					isMountedRef.current = true;
+				}
+			});
+		};
+		container.addEventListener("wheel", releaseManualSelectionOnUserScroll, { passive: true });
+		container.addEventListener("touchmove", releaseManualSelectionOnUserScroll, { passive: true });
+		container.addEventListener("pointerdown", releaseManualSelectionOnUserScroll);
+		ownerDocument.addEventListener("keydown", handleKeyDown);
+		container.addEventListener("scroll", handleScroll, { passive: true });
+		handleScroll();
+		return () => {
+			isMountedRef.current = false;
+			container.removeEventListener("wheel", releaseManualSelectionOnUserScroll);
+			container.removeEventListener("touchmove", releaseManualSelectionOnUserScroll);
+			container.removeEventListener("pointerdown", releaseManualSelectionOnUserScroll);
+			ownerDocument.removeEventListener("keydown", handleKeyDown);
+			container.removeEventListener("scroll", handleScroll);
+			if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+		};
+	}, [clearManualSelection, scrollRef]);
+	const lastEmittedIndexRef = (0, react.useRef)(safeIndex);
+	(0, react.useEffect)(() => {
+		const newSafeIndex = getSafeStepIndex(stepsRef.current.length, currentStepIndex);
+		if (newSafeIndex === lastEmittedIndexRef.current) return;
+		lastEmittedIndexRef.current = newSafeIndex;
+		activeIndexRef.current = newSafeIndex;
+		setActiveIndex(newSafeIndex);
+		setFurthestStepIndex((prev) => Math.max(prev, newSafeIndex));
+		const step = stepsRef.current[newSafeIndex];
+		if (!step) return;
+		const sectionElement = scrollRef.current?.querySelector(`#${CSS.escape(sectionIdRef.current(step.id))}`);
+		if (scrollRef.current && sectionElement) scrollSectionIntoView(scrollRef.current, sectionElement, scrollPaddingRef.current);
+	}, [currentStepIndex, scrollRef]);
+	return {
+		activeIndex,
+		furthestStepIndex,
+		scrollToSection: (0, react.useCallback)((index) => {
+			const step = stepsRef.current[index];
+			if (!step) return;
+			manualSelectionIndexRef.current = index;
+			activeIndexRef.current = index;
+			lastEmittedIndexRef.current = index;
+			setActiveIndex(index);
+			setFurthestStepIndex((prev) => Math.max(prev, index));
+			onStepChangeRef.current(index);
+			const container = scrollRef.current;
+			const sectionElement = container?.querySelector(`#${CSS.escape(sectionIdRef.current(step.id))}`);
+			if (container && sectionElement) scrollSectionIntoView(container, sectionElement, scrollPaddingRef.current);
+		}, [scrollRef])
+	};
+}
+function resolveScrollableActiveIndex(container, steps, sectionId) {
+	if (steps.length === 0) return {
+		activeIndex: 0,
+		commitFurthestStepIndex: false
+	};
+	const containerRect = container.getBoundingClientRect();
+	const anchorY = containerRect.top + Math.min(containerRect.height * .35, 220);
+	const isScrollable = container.scrollHeight > container.clientHeight + 1;
+	const isAtBottom = isScrollable && container.scrollTop + container.clientHeight >= container.scrollHeight - 1;
+	const isNearBottom = isScrollable && container.scrollTop + container.clientHeight >= container.scrollHeight - 4;
+	if (isAtBottom) return {
+		activeIndex: steps.length - 1,
+		commitFurthestStepIndex: false
+	};
+	let activeIndex = 0;
+	let highestScore = Number.NEGATIVE_INFINITY;
+	for (let i = 0; i < steps.length; i++) {
+		const sectionMetrics = getSectionMetrics(container, steps[i].id, sectionId, containerRect);
+		if (!sectionMetrics) continue;
+		const score = scoreScrollableStep({
+			stepIndex: i,
+			stepCount: steps.length,
+			containerRect,
+			anchorY,
+			isNearBottom,
+			...sectionMetrics
+		});
+		if (score >= highestScore) {
+			highestScore = score;
+			activeIndex = i;
+		}
+	}
+	return {
+		activeIndex,
+		commitFurthestStepIndex: true
+	};
+}
+const SCROLL_PADDING_PX = 32;
+function getSectionElement(container, stepId, sectionId) {
+	return container.querySelector(`#${CSS.escape(sectionId(stepId))}`);
+}
+function scrollSectionIntoView(container, sectionElement, padding) {
+	const elementTop = sectionElement.getBoundingClientRect().top;
+	const containerTop = container.getBoundingClientRect().top;
+	const targetScrollTop = container.scrollTop + (elementTop - containerTop) - padding;
+	container.scrollTo({
+		top: targetScrollTop,
+		behavior: "smooth"
+	});
+}
+function getSectionMetrics(container, stepId, sectionId, containerRect) {
+	const sectionElement = getSectionElement(container, stepId, sectionId);
+	if (!sectionElement) return null;
+	const sectionRect = sectionElement.getBoundingClientRect();
+	return {
+		sectionRect,
+		visibleHeight: getVisibleHeight(containerRect, sectionRect)
+	};
+}
+function getVisibleHeight(containerRect, sectionRect) {
+	return Math.max(0, Math.min(sectionRect.bottom, containerRect.bottom) - Math.max(sectionRect.top, containerRect.top));
+}
+function scoreScrollableStep({ stepIndex, stepCount, containerRect, sectionRect, visibleHeight, anchorY, isNearBottom }) {
+	const isVisible = visibleHeight > 0;
+	const focusBandTop = containerRect.top + Math.min(containerRect.height * .2, 140);
+	const focusBandBottom = containerRect.top + Math.min(containerRect.height * .55, 360);
+	const focusBandOverlap = getBandOverlapHeight(sectionRect, focusBandTop, focusBandBottom);
+	const distanceToFocusBand = focusBandOverlap > 0 ? 0 : Math.min(Math.abs(sectionRect.top - focusBandBottom), Math.abs(sectionRect.bottom - focusBandTop));
+	const lastStepProminent = stepIndex === stepCount - 1 && visibleHeight >= Math.min(sectionRect.height, containerRect.height) * .25 && sectionRect.top <= containerRect.top + containerRect.height * .65;
+	let score = isVisible ? visibleHeight : Number.NEGATIVE_INFINITY;
+	if (focusBandOverlap > 0) score += 12e3 + focusBandOverlap * 25;
+	if (sectionRect.top <= anchorY) score += 250;
+	score += Math.max(0, 1e3 - distanceToFocusBand);
+	if (isNearBottom && lastStepProminent && isVisible) score += 15e3;
+	return score;
+}
+function getBandOverlapHeight(sectionRect, bandTop, bandBottom) {
+	return Math.max(0, Math.min(sectionRect.bottom, bandBottom) - Math.max(sectionRect.top, bandTop));
+}
+function isScrollableNavigationKey(event) {
+	if (event.metaKey || event.ctrlKey || event.altKey) return false;
+	return [
+		"ArrowDown",
+		"ArrowUp",
+		"PageDown",
+		"PageUp",
+		"Home",
+		"End",
+		" "
+	].includes(event.key);
+}
+
+//#endregion
+//#region src/components/ui/wizard/WizardLayout.tsx
+function PagedLayout({ steps, currentStepIndex, furthestStepIndex: furthestStepIndexProp, onStepChange, onComplete, onCancel, navActions, header, variant, className }) {
+	const safeIndex = getSafeStepIndex(steps.length, currentStepIndex);
+	const resolvedFurthestStepIndex = useFurthestStepIndex(safeIndex, furthestStepIndexProp);
+	if (steps.length === 0) return null;
+	const isFirstStep = safeIndex === 0;
+	const isLastStep = safeIndex === steps.length - 1;
+	const currentStep = steps[safeIndex];
+	const canProceed = currentStep?.isValid !== false;
+	const handleNext = () => {
+		if (isLastStep) {
+			onComplete?.();
+			return;
+		}
+		onStepChange(safeIndex + 1);
+	};
+	const handlePrevious = () => {
+		if (!isFirstStep) onStepChange(safeIndex - 1);
+	};
+	const stepDefs = toStepDefs(steps, safeIndex);
+	const footer = /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		className: "shrink-0 border-t border-border bg-background px-8 py-4",
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "mx-auto max-w-5xl",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WizardNavigation, {
+				isFirstStep,
+				isLastStep,
+				canProceed,
+				onPrevious: handlePrevious,
+				onNext: handleNext,
+				onCancel,
+				extraActions: navActions
+			})
+		})
+	});
+	if (variant === "vertical") return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex h-full gap-6", className),
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "w-[220px] shrink-0 py-6 pl-6",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WizardStepper, {
+				variant: "vertical",
+				steps: stepDefs,
+				currentStepIndex: safeIndex,
+				furthestStepIndex: resolvedFurthestStepIndex,
+				onStepClick: onStepChange,
+				className: "h-full"
+			})
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "flex min-w-0 flex-1 flex-col overflow-hidden",
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "flex-1 overflow-y-auto p-8",
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "mx-auto max-w-5xl",
+					children: [header, currentStep?.component]
+				})
+			}), footer]
+		})]
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex h-full flex-col", className),
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "shrink-0 p-6 pb-0",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WizardStepper, {
+				variant: "horizontal",
+				steps: stepDefs,
+				currentStepIndex: safeIndex,
+				furthestStepIndex: resolvedFurthestStepIndex,
+				onStepClick: onStepChange
+			})
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "flex min-w-0 flex-1 flex-col overflow-hidden",
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "flex-1 overflow-y-auto p-8",
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "mx-auto max-w-5xl",
+					children: [header, currentStep?.component]
+				})
+			}), footer]
+		})]
+	});
+}
+function ScrollableLayout({ steps, currentStepIndex, onStepChange, header, onComplete, scrollPadding, className }) {
+	const instanceId = (0, react.useId)();
+	const scrollRef = (0, react.useRef)(null);
+	const sectionId = (0, react.useCallback)((stepId) => `wizard-section-${instanceId}-${stepId}`, [instanceId]);
+	const { activeIndex, furthestStepIndex, scrollToSection } = useScrollableWizardStepTracking({
+		steps,
+		currentStepIndex,
+		onStepChange,
+		scrollRef,
+		sectionId,
+		scrollPadding
+	});
+	if (steps.length === 0) return null;
+	const stepDefs = toStepDefs(steps, activeIndex);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex h-full gap-6", className),
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "w-[220px] shrink-0 py-6 pl-6",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WizardStepper, {
+				variant: "vertical",
+				steps: stepDefs,
+				currentStepIndex: activeIndex,
+				furthestStepIndex,
+				onStepClick: scrollToSection,
+				freeNavigation: true,
+				className: "h-full"
+			})
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			ref: scrollRef,
+			className: "flex min-w-0 flex-1 flex-col overflow-y-auto p-8",
+			children: [
+				header,
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "space-y-12",
+					children: steps.map((step) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("section", {
+						id: sectionId(step.id),
+						children: step.component
+					}, step.id))
+				}),
+				onComplete && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "flex justify-end pt-8",
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+						type: "button",
+						onClick: onComplete,
+						children: "Finish"
+					})
+				})
+			]
+		})]
+	});
+}
+function toStepDefs(steps, currentStepIndex) {
+	return steps.map((s, i) => {
+		const isInvalid = s.isInvalid ?? s.isValid === false;
+		const status = s.status ?? (i < currentStepIndex && !isInvalid ? "completed" : "pending");
+		return {
+			id: s.id,
+			title: s.title,
+			status,
+			isInvalid
+		};
+	});
+}
+/**
+* A layout component for the wizard.
+*
+* @param props - The props for the WizardLayout component.
+* @returns A React node representing the layout component.
+*/
+function WizardLayout(props) {
+	const { variant = "horizontal", ...rest } = props;
+	if (variant === "scrollable") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ScrollableLayout, {
+		steps: rest.steps,
+		currentStepIndex: rest.currentStepIndex,
+		onStepChange: rest.onStepChange,
+		header: rest.header,
+		onComplete: rest.onComplete,
+		scrollPadding: rest.scrollPadding,
+		className: rest.className
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PagedLayout, {
+		...rest,
+		variant
+	});
+}
+
+//#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 +2595,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 +2614,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 +2723,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 +2757,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 +2819,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 +6278,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 +6359,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;
@@ -5382,6 +6400,9 @@ exports.TooltipProvider = TooltipProvider;
 exports.TooltipTrigger = TooltipTrigger;
 exports.UrlField = UrlField;
 exports.ViewContractStateButton = ViewContractStateButton;
+exports.WizardLayout = WizardLayout;
+exports.WizardNavigation = WizardNavigation;
+exports.WizardStepper = WizardStepper;
 exports.buttonVariants = buttonVariants;
 exports.computeChildTouched = computeChildTouched;
 exports.createFocusManager = createFocusManager;
@@ -5399,6 +6420,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;