@openzeppelin/ui-components 3.3.0 → 3.4.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as AccordionPrimitive from "@radix-ui/react-accordion";
 import { VariantProps } from "class-variance-authority";
 import * as React$2 from "react";
-import React$1, { ForwardedRef, JSX, ReactElement, ReactNode } from "react";
+import React$1, { Context, ForwardedRef, JSX, ReactElement, ReactNode } from "react";
 import { AddressCandidateClassification } from "@openzeppelin/ui-utils";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
@@ -16,9 +16,9 @@ import * as ProgressPrimitive from "@radix-ui/react-progress";
 import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
 import * as SelectPrimitive from "@radix-ui/react-select";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
-import { AddressLabelResolver, AddressSuggestion, AddressSuggestionResolver, AddressingCapability, ContractSchema, Ecosystem, EcosystemMetadata, EnumValue, FieldValidation, FormFieldType, FunctionParameter, MapEntry, NetworkConfig, NetworkType, RelayerDetails, RelayerDetailsRich, RuntimeCapability, TypeMappingCapability } from "@openzeppelin/ui-types";
+import { AddressLabelResolver, AddressNameResolver, AddressSuggestion, AddressSuggestionResolver, AddressingCapability, ContractSchema, Ecosystem, EcosystemMetadata, EnumValue, FieldValidation, FormFieldType, FunctionParameter, MapEntry, NameResolutionError, NameResolver, NetworkConfig, NetworkType, RelayerDetails, RelayerDetailsRich, ResolutionResult, ResolvedAddress, ResolvedName, RuntimeCapability, TypeMappingCapability } from "@openzeppelin/ui-types";
 import { ToasterProps } from "sonner";
-import * as class_variance_authority_types1 from "class-variance-authority/types";
+import * as class_variance_authority_types0 from "class-variance-authority/types";
 
 //#region src/version.d.ts
 declare const VERSION: string;
@@ -26,13 +26,13 @@ declare const VERSION: string;
 //#region src/components/ui/accordion.d.ts
 declare const accordionItemVariants: (props?: ({
   variant?: "default" | "card" | null | undefined;
-} & class_variance_authority_types1.ClassProp) | undefined) => string;
+} & class_variance_authority_types0.ClassProp) | undefined) => string;
 declare const accordionTriggerVariants: (props?: ({
   variant?: "default" | "card" | null | undefined;
-} & class_variance_authority_types1.ClassProp) | undefined) => string;
+} & class_variance_authority_types0.ClassProp) | undefined) => string;
 declare const accordionContentVariants: (props?: ({
   variant?: "default" | "card" | null | undefined;
-} & class_variance_authority_types1.ClassProp) | undefined) => string;
+} & class_variance_authority_types0.ClassProp) | undefined) => string;
 type AccordionVariant = 'default' | 'card';
 type AccordionProps = (AccordionPrimitive.AccordionSingleProps | AccordionPrimitive.AccordionMultipleProps) & {
   variant?: AccordionVariant;
@@ -45,6 +45,18 @@ declare const AccordionTrigger: React$2.ForwardRefExoticComponent<AccordionTrigg
 interface AccordionContentProps extends React$2.ComponentPropsWithoutRef<typeof AccordionPrimitive.Content>, VariantProps<typeof accordionContentVariants> {}
 declare const AccordionContent: React$2.ForwardRefExoticComponent<AccordionContentProps & React$2.RefAttributes<HTMLDivElement>>;
 //#endregion
+//#region src/components/ui/address-display/address-avatar.d.ts
+/**
+ * Visual treatment for {@link AddressAvatar}.
+ *
+ * - `'fill'` – a square avatar that stretches to the parent slot's full
+ *   height and sits flush against its edges (default). Intended for a chip
+ *   whose container clips it with `overflow-hidden` + a border radius.
+ * - `'circle'` – small round avatar sitting inline with the text (the
+ *   original look, kept as an opt-in).
+ */
+type AddressAvatarVariant = 'circle' | 'fill';
+//#endregion
 //#region src/components/ui/address-display/address-display.d.ts
 /**
  * Visual style for the component container.
@@ -123,9 +135,12 @@ interface AddressDisplayProps extends React$2.HTMLAttributes<HTMLDivElement> {
    */
   networkId?: string;
   /**
-   * When `true`, skip label resolution from `AddressLabelContext`.
-   * Useful for rendering an address without alias decoration (e.g. in
-   * a contract selector where the contract name is already shown).
+   * When `true`, render the instance fully raw: skip label resolution from
+   * `AddressLabelContext` AND suppress any injected resolved name
+   * (`resolvedName` prop / `AddressNameContext`). Useful for rendering an
+   * address without any decoration (e.g. in a contract selector where the
+   * contract name is already shown) — existing `disableLabel` call-sites
+   * must not sprout a name once a resolver is wired app-wide.
    * @default false
    */
   disableLabel?: boolean;
@@ -142,6 +157,38 @@ interface AddressDisplayProps extends React$2.HTMLAttributes<HTMLDivElement> {
    * @default "chip"
    */
   variant?: AddressDisplayVariant;
+  /**
+   * Optional presentational leading element (e.g. an avatar or icon), rendered
+   * before the label/address block and vertically centered against it. Purely
+   * visual — a `React.ReactNode`, not a capability, so this component stays
+   * chain-agnostic. When omitted (the default at every existing call-site), the
+   * rendered DOM and layout are byte-for-byte identical to the pre-avatar
+   * component: no wrapper element, no reserved slot, in both render branches.
+   */
+  avatar?: React$2.ReactNode;
+  /**
+   * Visual treatment for the leading avatar (both the record-constructed ENS
+   * avatar and an explicit `avatar` node):
+   *
+   * - `'fill'` – a square avatar that stretches to the chip's full height and
+   *   sits flush against its top, bottom, and left edges (default; the chip
+   *   clips its outer corners). No effect when no avatar is shown.
+   * - `'circle'` – small round avatar sitting inline with the text (the
+   *   original look, kept as an opt-in).
+   *
+   * @default "fill"
+   */
+  avatarVariant?: AddressAvatarVariant;
+  /**
+   * An already-resolved reverse name record for this address (value type).
+   * Highest precedence for the name channel — shadows the
+   * `AddressNameContext` resolver, exactly as `label` shadows
+   * `AddressLabelContext` (INV-120). The record's name renders only when
+   * `forwardVerified === true` (INV-52, LOCKED): a mismatched record is
+   * suppressed to hex — never name-alone, never name+warning. `undefined`
+   * falls back to the context (if any), then to hex.
+   */
+  resolvedName?: ResolvedName;
   /**
    * Additional CSS classes
    */
@@ -149,15 +196,27 @@ interface AddressDisplayProps extends React$2.HTMLAttributes<HTMLDivElement> {
 }
 /**
  * Displays a blockchain address with optional truncation, copy button,
- * explorer link, tooltip, and human-readable label.
+ * explorer link, tooltip, human-readable label, and (when an already-resolved
+ * record is injected) a forward-verified name + avatar.
  *
- * Labels are resolved in priority order:
+ * Labels are resolved in priority order (INV-56):
  * 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).
+ * 3. Forward-verified resolved name (`resolvedName` prop, else
+ *    `AddressNameContext` via `AddressNameProvider`) — a record with
+ *    `forwardVerified: false` is suppressed to hex (INV-52, LOCKED)
+ * 4. No label (renders address only, identical to previous behavior)
+ *
+ * The component is synchronous and capability-free (INV-121): it never
+ * resolves anything itself — it reads injected values. Hex renders on first
+ * commit; the name+avatar swap in when the react layer feeds an updated
+ * record (progressive enhancement, INV-61). With no `resolvedName` and no
+ * `AddressNameProvider`, output is byte-identical to the pre-enhancement
+ * component (INV-54, LOCKED).
+ *
+ * Pass `disableLabel` to render fully raw — it suppresses both the context
+ * alias and any injected resolved name (e.g. when the surrounding UI already
+ * shows a name, such as a contract selector).
  *
  * @example
  * ```tsx
@@ -184,6 +243,14 @@ interface AddressDisplayProps extends React$2.HTMLAttributes<HTMLDivElement> {
  * // Inline variant (no chip background) — useful inside wallet bars
  * <AddressDisplay address="0x742d35Cc..." variant="inline" showTooltip showCopyButton />
  *
+ * // Reverse-resolved name + avatar via an injected value (react layer owns the async)
+ * <AddressDisplay address="0x742d35Cc..." resolvedName={record} showCopyButton />
+ *
+ * // Or subtree-wide via context (rows stay plain <AddressDisplay/>)
+ * <AddressNameProvider resolveAddressName={readFromResolutionCache}>
+ *   <AddressDisplay address="0x742d35Cc..." />
+ * </AddressNameProvider>
+ *
  * // Truncate only when an alias/label is present (full address when unlabeled)
  * <AddressDisplay address="G..." truncateWhenLabeled />
  * ```
@@ -204,6 +271,9 @@ declare function AddressDisplay({
   disableLabel,
   showTooltip,
   variant,
+  avatar,
+  avatarVariant,
+  resolvedName,
   className,
   onPointerEnter,
   onPointerLeave,
@@ -275,10 +345,62 @@ interface UseAddressLabelResult {
  */
 declare function useAddressLabel(address: string, networkId?: string): UseAddressLabelResult;
 //#endregion
+//#region src/components/ui/address-display/address-name-context.d.ts
+/**
+ * Props for `AddressNameProvider`.
+ *
+ * Accepts the same shape as `AddressNameResolver` so the provider can be
+ * spread directly from a resolver source: `<AddressNameProvider {...resolver}>`.
+ */
+interface AddressNameProviderProps extends AddressNameResolver {
+  children: React$2.ReactNode;
+}
+/**
+ * Provides reverse-name resolution to all `AddressDisplay` instances in the
+ * subtree. `resolveAddressName` MUST be synchronous — it is called during
+ * render (INV-122). A resolver that returns `undefined` for an address is
+ * behaviorally identical to mounting no provider (INV-54).
+ *
+ * @param props - Resolver function and children
+ */
+declare function AddressNameProvider({
+  children,
+  resolveAddressName
+}: AddressNameProviderProps): React$2.ReactElement;
+//#endregion
+//#region src/components/ui/address-display/use-address-name.d.ts
+/**
+ * Return type for the `useAddressName` convenience hook.
+ */
+interface UseAddressNameResult {
+  /** Resolved record, or `undefined` if no provider/record exists */
+  record: ResolvedName | undefined;
+}
+/**
+ * Reads the `AddressNameContext` for one address, synchronously (INV-122).
+ * Returns `{ record: undefined }` when no provider is mounted — never throws,
+ * never suspends. Note the record is returned verbatim: callers rendering a
+ * name from it must apply the same `forwardVerified === true` gate that
+ * `AddressDisplay` applies (INV-52).
+ *
+ * @param address - The blockchain address to reverse-resolve
+ * @param networkId - Optional network identifier scoping the lookup
+ * @returns The current best-known record for the address
+ *
+ * @example
+ * ```tsx
+ * function EnsBadge({ address }: { address: string }) {
+ *   const { record } = useAddressName(address);
+ *   return record?.forwardVerified ? <Badge>{record.name}</Badge> : null;
+ * }
+ * ```
+ */
+declare function useAddressName(address: string, networkId?: string): UseAddressNameResult;
+//#endregion
 //#region src/components/ui/alert.d.ts
 declare const Alert: React$2.ForwardRefExoticComponent<React$2.HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
   variant?: "default" | "destructive" | "success" | null | undefined;
-} & class_variance_authority_types1.ClassProp) | undefined) => string> & React$2.RefAttributes<HTMLDivElement>>;
+} & class_variance_authority_types0.ClassProp) | undefined) => string> & React$2.RefAttributes<HTMLDivElement>>;
 declare const AlertTitle: React$2.ForwardRefExoticComponent<React$2.HTMLAttributes<HTMLHeadingElement> & React$2.RefAttributes<HTMLParagraphElement>>;
 declare const AlertDescription: React$2.ForwardRefExoticComponent<React$2.HTMLAttributes<HTMLParagraphElement> & React$2.RefAttributes<HTMLParagraphElement>>;
 //#endregion
@@ -332,7 +454,7 @@ declare const Banner: React$2.ForwardRefExoticComponent<BannerProps & React$2.Re
 declare const buttonVariants: (props?: ({
   variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
   size?: "default" | "sm" | "lg" | "icon" | null | undefined;
-} & class_variance_authority_types1.ClassProp) | undefined) => string;
+} & class_variance_authority_types0.ClassProp) | undefined) => string;
 //#endregion
 //#region src/components/ui/button.d.ts
 interface ButtonProps extends React$2.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
@@ -1330,6 +1452,18 @@ interface AddressFieldProps<TFieldValues extends FieldValues = FieldValues> exte
    * so callers can perform additional side-effects beyond filling the field value.
    */
   onSuggestionSelect?: (suggestion: AddressSuggestion) => void;
+  /**
+   * Fired when the resolved-and-name-matched name changes. Emits the resolved
+   * NAME (not the hex) on `resolved` + name-match, and `undefined` in every
+   * other state (idle / debouncing / loading / error / hex / cleared).
+   *
+   * Pure notification for consumers that want the human-readable name (e.g.
+   * the address book's alias suggestion, SF-5 INV-109..111). It reads existing
+   * resolution state and does NOT participate in the resolved-hex write path
+   * (INV-75/79/80/81/85 unaffected). With no injected resolver it only ever
+   * emits `undefined`, so the field stays behavior-identical (INV-82).
+   */
+  onResolvedNameChange?: (name: string | undefined) => void;
 }
 /**
  * Address input field component specifically designed for blockchain addresses via React Hook Form integration.
@@ -1358,7 +1492,22 @@ interface AddressFieldProps<TFieldValues extends FieldValues = FieldValues> exte
  *    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.
+ * Enter, Escape), click-outside dismissal, and ARIA listbox semantics — all provided by
+ * the shared headless `useAddressSuggestionField` hook + `AddressSuggestionList`.
+ *
+ * **Inline name resolution (SF-3, opt-in via context).** When a
+ * `NameResolverProvider` is mounted, the field also accepts a name (e.g.
+ * `alice.eth`): the name is resolved inline through the injected `resolveName`
+ * and the RHF form value becomes the resolved hex — never the name, never a
+ * silently-coerced value. The correctness spine is a shadow-state model:
+ * the `<input>` always shows the typed string (`inputValue`, INV-69); the RHF
+ * value is `''` for every unresolved name state so submit stays gated with no
+ * async validator (INV-75); the single name→hex write fires only on
+ * `resolved` + normalized name-match (INV-79/80). With **no** provider mounted
+ * every resolution branch below is dead code and the field is byte-identical
+ * to its pre-ENS behavior (INV-82 — the LOCKED backward-compat guarantee).
+ * The component stays capability-free: it never reads a runtime or wallet
+ * state; everything arrives through the injected context (INV-118).
  */
 declare function AddressField<TFieldValues extends FieldValues = FieldValues>({
   id,
@@ -1372,7 +1521,8 @@ declare function AddressField<TFieldValues extends FieldValues = FieldValues>({
   addressing,
   readOnly,
   suggestions: suggestionsProp,
-  onSuggestionSelect
+  onSuggestionSelect,
+  onResolvedNameChange
 }: AddressFieldProps<TFieldValues>): React$1.ReactElement;
 declare namespace AddressField {
   var displayName: string;
@@ -1524,6 +1674,248 @@ interface UseAddressSuggestionsResult {
 /** Resolves address suggestions from the nearest `AddressSuggestionProvider`. */
 declare function useAddressSuggestions(query: string, networkId?: string): UseAddressSuggestionsResult;
 //#endregion
+//#region src/components/fields/address-suggestion/useAddressSuggestionField.d.ts
+/** Arguments for {@link useAddressSuggestionField}. */
+interface UseAddressSuggestionFieldArgs {
+  /** The current input text — drives the debounce and dropdown visibility. */
+  readonly inputValue: string;
+  /**
+   * Explicit suggestion list. When an array, it overrides context resolution and
+   * is rendered as-is (no cap). `false` disables suggestions entirely (even with
+   * a provider mounted). `undefined` falls back to context resolution.
+   */
+  readonly suggestions?: AddressSuggestion[] | false;
+  /** Optional network id forwarded to the context resolver for scoping. */
+  readonly networkId?: string;
+}
+/** State and handlers returned by {@link useAddressSuggestionField}. */
+interface UseAddressSuggestionFieldResult {
+  /** Ref for the field container — used for click-outside detection. */
+  readonly containerRef: React.RefObject<HTMLDivElement | null>;
+  /** The suggestions to render (context-resolved + capped, or the explicit array). */
+  readonly resolvedSuggestions: AddressSuggestion[];
+  /** `true` when the dropdown is open AND there is at least one suggestion. */
+  readonly hasSuggestions: boolean;
+  /** Index of the keyboard-highlighted option, or `-1` when none. */
+  readonly highlightedIndex: number;
+  /** `true` when suggestions are explicitly disabled (`suggestions === false`). */
+  readonly suggestionsDisabled: boolean;
+  /** Set the highlighted option index (e.g. on hover). */
+  readonly setHighlightedIndex: (index: number) => void;
+  /** Close the dropdown and clear the highlight. */
+  readonly closeSuggestions: () => void;
+  /** Notify the hook of an input change — opens/closes the dropdown and resets highlight. */
+  readonly onInputChange: (value: string) => void;
+  /** Container-level keydown handler: wrapping ArrowUp / ArrowDown navigation. */
+  readonly onContainerKeyDown: (e: React.KeyboardEvent) => void;
+}
+/**
+ * Headless address-suggestion dropdown behavior. See the module docstring for
+ * the full behavior contract.
+ *
+ * @param args - {@link UseAddressSuggestionFieldArgs}.
+ * @returns {@link UseAddressSuggestionFieldResult}.
+ */
+declare function useAddressSuggestionField({
+  inputValue,
+  suggestions: suggestionsProp,
+  networkId
+}: UseAddressSuggestionFieldArgs): UseAddressSuggestionFieldResult;
+//#endregion
+//#region src/components/fields/address-suggestion/AddressSuggestionList.d.ts
+/** Props for {@link AddressSuggestionList}. */
+interface AddressSuggestionListProps {
+  /** Field id — anchors the listbox id (`${id}-suggestions`) and option ids. */
+  readonly id: string;
+  /** The suggestions to render. */
+  readonly suggestions: AddressSuggestion[];
+  /** Index of the currently highlighted option, or `-1`. */
+  readonly highlightedIndex: number;
+  /** Called when an option is selected (click / mouse-down). */
+  readonly onSelect: (suggestion: AddressSuggestion) => void;
+  /** Called when an option is hovered, to sync the highlight. */
+  readonly onHighlight: (index: number) => void;
+}
+/**
+ * Render the suggestion dropdown. Returns `null` when there are no suggestions
+ * (the consuming field also gates on `hasSuggestions`, so this is a safety net).
+ *
+ * @param props - {@link AddressSuggestionListProps}.
+ */
+declare function AddressSuggestionList({
+  id,
+  suggestions,
+  highlightedIndex,
+  onSelect,
+  onHighlight
+}: AddressSuggestionListProps): React$2.ReactElement | null;
+declare namespace AddressSuggestionList {
+  var displayName: string;
+}
+//#endregion
+//#region src/components/fields/name-resolution/context.d.ts
+/**
+ * Value held by NameResolverContext. Extends the SF-3 injection seam with
+ * optional network context for SF-6 chain-scope gating only.
+ */
+interface NameResolverContextValue extends NameResolver {
+  /**
+   * Active network id for chain-scope submit gating (opaque string).
+   * When absent, `isChainScopeMismatch` is never true and coinType wrong-chain
+   * protection is the integrator's responsibility.
+   */
+  readonly activeNetworkId?: string | null;
+  /**
+   * Optional human-readable active network name — interpolated into the
+   * chain-scope mismatch message only (same seam as INV-78 networkName).
+   */
+  readonly activeNetworkName?: string;
+}
+/**
+ * @internal Shared context instance consumed by both AddressField and
+ * NameResolverProvider (INV-118). Kept in its own file so component files
+ * export only components (required by React Fast Refresh).
+ *
+ * `null` means no provider is mounted — every ENS branch in `AddressField` is
+ * then dead code and the field is byte-identical to its pre-ENS behavior
+ * (INV-82).
+ */
+declare const NameResolverContext: Context<NameResolverContextValue | null>;
+//#endregion
+//#region src/components/fields/name-resolution/name-resolver-context.d.ts
+/**
+ * Props for `NameResolverProvider`.
+ *
+ * Accepts the same shape as `NameResolver` so the provider can be spread
+ * directly from a resolver hook: `<NameResolverProvider {...resolver}>` —
+ * the same idiom as `AddressSuggestionProvider` / `AddressLabelProvider`.
+ */
+interface NameResolverProviderProps extends NameResolverContextValue {
+  children: React$2.ReactNode;
+}
+/**
+ * Provides forward name resolution to all `AddressField` instances in the
+ * subtree (zero call-site wiring, SC-001). Both functions are optional: an
+ * absent `resolveName` means forward resolution is unsupported and a typed
+ * name surfaces `UNSUPPORTED_NETWORK` (INV-119 / SC-006).
+ *
+ * ## Stable resolver identity (integrator contract)
+ *
+ * The injected resolver **must be referentially stable across renders** —
+ * memoize it (e.g. `useMemo`) or use `useRuntimeNameResolver` from
+ * `@openzeppelin/ui-react`, which is stable by construction. A resolver whose
+ * function identity changes on every render (e.g. a fresh inline function) is a
+ * misconfiguration: the field keys inline resolution on that identity, so a
+ * churning identity would otherwise re-dispatch on every render — an unbounded
+ * RPC loop on a funds path.
+ *
+ * The base component **detects and withstands** this (it is not merely a caveat):
+ * dispatch is bounded per resolution intent so a churning resolver can never drive
+ * an unbounded loop (INV-123), a one-shot development-only warning names the
+ * misconfiguration (INV-124), and the field degrades to a **safe gated state**
+ * (empty value, submit blocked — never a wrong address, never a throw; INV-125)
+ * until the resolver is memoized. A **genuine** resolver/network swap — a single
+ * identity change for a given input — is still honored and re-resolves within
+ * budget (INV-119). The bound is a backstop; the contract is a stable identity.
+ *
+ * @param props - Injected resolver functions and children
+ */
+declare function NameResolverProvider({
+  children,
+  isValidName,
+  resolveName,
+  activeNetworkId,
+  activeNetworkName
+}: NameResolverProviderProps): React$2.ReactElement;
+//#endregion
+//#region src/components/fields/name-resolution/useNameResolver.d.ts
+/**
+ * Read the injected resolver context. Returns `null` when no
+ * `NameResolverProvider` is mounted — the consuming field must then treat
+ * every ENS branch as dead code (INV-82).
+ *
+ * @returns The extended context value, or `null` when no provider is mounted.
+ */
+declare function useNameResolver(): NameResolverContextValue | null;
+//#endregion
+//#region src/components/fields/name-resolution/useInjectedNameResolution.d.ts
+/**
+ * Default debounce window (ms) for typed names — mirrors SF-2's
+ * `forwardDebounceMs` default so the field and the bare hook feel identical.
+ */
+declare const NAME_RESOLUTION_DEBOUNCE_MS = 300;
+/** Forward resolver function injected through `NameResolverContext`. */
+type InjectedResolveName = (name: string) => Promise<ResolutionResult<ResolvedAddress>>;
+/**
+ * Machine result — a discriminated union keyed on `status`, shaped like SF-2's
+ * `UseResolveNameResult` so downstream rendering logic carries over verbatim.
+ * `name` is always the normalized (trim + lowercase) input the arm refers to.
+ */
+type InjectedNameResolutionResult = {
+  readonly status: 'idle';
+} | {
+  readonly status: 'debouncing';
+  readonly name: string;
+} | {
+  readonly status: 'loading';
+  readonly name: string;
+} | {
+  readonly status: 'resolved';
+  readonly name: string;
+  readonly data: ResolvedAddress;
+} | {
+  readonly status: 'error';
+  readonly name: string;
+  readonly error: NameResolutionError;
+  readonly retry: () => void;
+};
+/** Parameters for {@link useInjectedNameResolution}. */
+interface UseInjectedNameResolutionParams {
+  /** The raw typed input (the field's display string). Normalized internally. */
+  readonly input: string;
+  /**
+   * INV-83: `true` only when `classification === 'name-candidate'` AND an
+   * injected `resolveName` exists. `false` forces `idle` with zero calls.
+   */
+  readonly enabled: boolean;
+  /** The injected forward resolver. Absent → the machine stays `idle`. */
+  readonly resolveName?: InjectedResolveName;
+  /** Debounce override (ms); `<= 0` disables debouncing. */
+  readonly debounceMs?: number;
+}
+/**
+ * Debounce + dispatch + status derivation over an injected `resolveName`.
+ *
+ * Guarantees:
+ * - INV-83: no call unless `enabled` (name-candidate + injected method), and
+ *   never for a debounced copy that lags the current normalized input.
+ * - INV-117: a settled result whose requested name ≠ the current debounced
+ *   input is discarded (last-write-wins at the component boundary).
+ * - INV-87: a rejecting resolver (contract violation) is mapped to a typed
+ *   `ADAPTER_ERROR` — nothing throws into the render tree.
+ * - INV-123: resolver dispatches are bounded per resolution intent (normalized
+ *   debounced input × retry attempt) at {@link MAX_DISPATCHES_PER_INTENT},
+ *   regardless of render count or resolver-identity oscillation; the budget
+ *   resets on intent change or when leaving the name-resolution path — never on
+ *   `settled.source` mismatch; `retry()` never consumes an existing budget.
+ * - INV-124: an identity-churning resolver that exhausts the budget triggers a
+ *   one-shot, development-only `logger.warn` (silent in production).
+ * - INV-125: under sustained churn the field stays in the safe gated state — the
+ *   perpetually-changing identity keeps failing the `settled.source` check, so
+ *   the machine derives `loading`, never `resolved`; combined with INV-87 it
+ *   never throws and never writes a hex.
+ * - No `setState` after unmount: every dispatch is cancelled on cleanup.
+ *
+ * @param params - {@link UseInjectedNameResolutionParams}
+ * @returns The current {@link InjectedNameResolutionResult}.
+ */
+declare function useInjectedNameResolution({
+  input,
+  enabled,
+  resolveName,
+  debounceMs
+}: UseInjectedNameResolutionParams): InjectedNameResolutionResult;
+//#endregion
 //#region src/components/fields/AmountField.d.ts
 /**
  * AmountField component properties
@@ -2665,6 +3057,15 @@ interface TextFieldProps<TFieldValues extends FieldValues = FieldValues> extends
    * Placeholder text displayed when the field is empty
    */
   placeholder?: string;
+  /**
+   * Fired with the new value on USER-originated edits only — keystrokes and the
+   * Escape-clear — never on programmatic writes (`setValue`/`reset`). This is
+   * the discriminator consumers need to tell "the user claimed this field" from
+   * "code seeded this field" (e.g. the address book's ENS alias suggestion,
+   * SF-5 INV-103/INV-105); RHF's `dirtyFields` cannot express it because any
+   * form-wide dirty recompute retroactively marks a seeded value dirty.
+   */
+  onUserEdit?: (value: string) => void;
 }
 /**
  * Text input field component specifically designed for React Hook Form integration.
@@ -2693,7 +3094,8 @@ declare function TextField<TFieldValues extends FieldValues = FieldValues>({
   name,
   width,
   validation,
-  readOnly
+  readOnly,
+  onUserEdit
 }: TextFieldProps<TFieldValues>): React$1.ReactElement;
 declare namespace TextField {
   var displayName: string;
@@ -3093,5 +3495,5 @@ declare const Toaster: ({
   ...props
 }: ToasterProps) => JSX.Element;
 //#endregion
-export { AccessibilityProps, Accordion, AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, AddressDisplay, type AddressDisplayVariant, AddressField, AddressLabelProvider, type AddressLabelProviderProps, AddressListEntryMode, AddressListField, AddressListFieldLabels, AddressListFieldProps, AddressSuggestionProvider, type AddressSuggestionProviderProps, Alert, AlertDescription, AlertTitle, AmountField, AmountFieldProps, ArrayField, ArrayFieldProps, ArrayObjectField, ArrayObjectFieldProps, Banner, BannerProps, BannerSize, BannerVariant, BaseField, BaseFieldProps, BigIntField, BigIntFieldProps, BooleanField, BooleanFieldProps, Button, ButtonProps, BytesField, BytesFieldProps, Calendar, CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, DEFAULT_ADDRESS_LIST_FIELD_LABELS, type DateRange, DateRangePicker, DateRangePickerProps, DateTimeField, DateTimeFieldProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EcosystemDropdown, EcosystemDropdownOption, EcosystemDropdownProps, EcosystemIcon, EcosystemIconProps, EmptyState, EmptyStateProps, EnumField, EnumFieldProps, EnumFieldValue, EnumMetadata, EnumVariant, ErrorMessage, ExternalLink, FileUploadField, FileUploadFieldProps, Footer, FooterProps, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, GroupedSelectOption, Header, HeaderProps, INTEGER_HTML_PATTERN, INTEGER_INPUT_PATTERN, INTEGER_PATTERN, Input, InputProps, Label, LoadingButton, LoadingButtonProps, MapEntryRow, MapField, MapFieldProps, MidnightIcon, NetworkAvailabilityNotice, type NetworkAvailabilityNoticeProps, type NetworkError, NetworkErrorNotificationProvider, type NetworkErrorType, NetworkIcon, NetworkIconProps, NetworkSelector, NetworkSelectorProps, NetworkServiceErrorBanner, type NetworkServiceErrorBannerProps, NetworkStatusBadge, NumberField, NumberFieldProps, ObjectField, ObjectFieldProps, OptionGroup, OverflowMenu, OverflowMenuItem, OverflowMenuProps, PasswordField, PasswordFieldProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioField, RadioFieldProps, RadioGroup, RadioGroupItem, RadioOption, RelayerDetailsCard, type RelayerDetailsCardProps, Select, SelectContent, SelectField, SelectFieldProps, SelectGroup, SelectGroupedField, SelectGroupedFieldProps, SelectItem, SelectLabel, SelectOption, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SidebarButton, type SidebarButtonProps, SidebarGroup, type SidebarGroupProps, SidebarLayout, type SidebarLayoutProps, SidebarSection, type SidebarSectionProps, type StepStatus, type StepVisualState, Tabs, TabsContent, TabsList, TabsTrigger, TextAreaField, TextAreaFieldProps, TextField, TextFieldProps, Textarea, TextareaProps, Toaster, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UrlField, type UseAddressLabelResult, type UseAddressSuggestionsResult, VERSION, ViewContractStateButton, WizardLayout, type WizardLayoutProps, WizardNavigation, type WizardNavigationProps, type WizardStepConfig, type WizardStepDef, WizardStepper, type WizardStepperProps, buildAddressListPreviewSummary, buttonVariants, computeChildTouched, createFocusManager, createValidationResult, formatAddressBulkSummary, formatValidationError, getAccessibilityProps, getDescribedById, getErrorMessage, getValidationStateClasses, getWidthClasses, handleEscapeKey, handleKeyboardEvent, handleNumericKeys, handleToggleKeys, handleValidationError, hasFieldError, isDuplicateMapKey, resolveAddressListFieldLabels, useAddressLabel, useAddressSuggestions, useDuplicateKeyIndexes, useMapFieldSync, useNetworkErrorAwareAdapter, useNetworkErrorReporter, useNetworkErrors, validateField, validateMapEntries, validateMapStructure };
+export { AccessibilityProps, Accordion, AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, type AddressAvatarVariant, AddressDisplay, type AddressDisplayProps, type AddressDisplayVariant, AddressField, AddressFieldProps, AddressLabelProvider, type AddressLabelProviderProps, AddressListEntryMode, AddressListField, AddressListFieldLabels, AddressListFieldProps, AddressNameProvider, type AddressNameProviderProps, AddressSuggestionList, type AddressSuggestionListProps, AddressSuggestionProvider, type AddressSuggestionProviderProps, Alert, AlertDescription, AlertTitle, AmountField, AmountFieldProps, ArrayField, ArrayFieldProps, ArrayObjectField, ArrayObjectFieldProps, Banner, BannerProps, BannerSize, BannerVariant, BaseField, BaseFieldProps, BigIntField, BigIntFieldProps, BooleanField, BooleanFieldProps, Button, ButtonProps, BytesField, BytesFieldProps, Calendar, CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, DEFAULT_ADDRESS_LIST_FIELD_LABELS, type DateRange, DateRangePicker, DateRangePickerProps, DateTimeField, DateTimeFieldProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EcosystemDropdown, EcosystemDropdownOption, EcosystemDropdownProps, EcosystemIcon, EcosystemIconProps, EmptyState, EmptyStateProps, EnumField, EnumFieldProps, EnumFieldValue, EnumMetadata, EnumVariant, ErrorMessage, ExternalLink, FileUploadField, FileUploadFieldProps, Footer, FooterProps, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, GroupedSelectOption, Header, HeaderProps, INTEGER_HTML_PATTERN, INTEGER_INPUT_PATTERN, INTEGER_PATTERN, type InjectedNameResolutionResult, type InjectedResolveName, Input, InputProps, Label, LoadingButton, LoadingButtonProps, MapEntryRow, MapField, MapFieldProps, MidnightIcon, NAME_RESOLUTION_DEBOUNCE_MS, NameResolverContext, NameResolverProvider, type NameResolverProviderProps, NetworkAvailabilityNotice, type NetworkAvailabilityNoticeProps, type NetworkError, NetworkErrorNotificationProvider, type NetworkErrorType, NetworkIcon, NetworkIconProps, NetworkSelector, NetworkSelectorProps, NetworkServiceErrorBanner, type NetworkServiceErrorBannerProps, NetworkStatusBadge, NumberField, NumberFieldProps, ObjectField, ObjectFieldProps, OptionGroup, OverflowMenu, OverflowMenuItem, OverflowMenuProps, PasswordField, PasswordFieldProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioField, RadioFieldProps, RadioGroup, RadioGroupItem, RadioOption, RelayerDetailsCard, type RelayerDetailsCardProps, Select, SelectContent, SelectField, SelectFieldProps, SelectGroup, SelectGroupedField, SelectGroupedFieldProps, SelectItem, SelectLabel, SelectOption, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SidebarButton, type SidebarButtonProps, SidebarGroup, type SidebarGroupProps, SidebarLayout, type SidebarLayoutProps, SidebarSection, type SidebarSectionProps, type StepStatus, type StepVisualState, Tabs, TabsContent, TabsList, TabsTrigger, TextAreaField, TextAreaFieldProps, TextField, TextFieldProps, Textarea, TextareaProps, Toaster, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UrlField, type UseAddressLabelResult, type UseAddressNameResult, type UseAddressSuggestionFieldArgs, type UseAddressSuggestionFieldResult, type UseAddressSuggestionsResult, type UseInjectedNameResolutionParams, VERSION, ViewContractStateButton, WizardLayout, type WizardLayoutProps, WizardNavigation, type WizardNavigationProps, type WizardStepConfig, type WizardStepDef, WizardStepper, type WizardStepperProps, buildAddressListPreviewSummary, buttonVariants, computeChildTouched, createFocusManager, createValidationResult, formatAddressBulkSummary, formatValidationError, getAccessibilityProps, getDescribedById, getErrorMessage, getValidationStateClasses, getWidthClasses, handleEscapeKey, handleKeyboardEvent, handleNumericKeys, handleToggleKeys, handleValidationError, hasFieldError, isDuplicateMapKey, resolveAddressListFieldLabels, useAddressLabel, useAddressName, useAddressSuggestionField, useAddressSuggestions, useDuplicateKeyIndexes, useInjectedNameResolution, useMapFieldSync, useNameResolver, useNetworkErrorAwareAdapter, useNetworkErrorReporter, useNetworkErrors, validateField, validateMapEntries, validateMapStructure };
 //# sourceMappingURL=index.d.mts.map