@wakastellar/ui 1.0.12 → 2.1.0

package/src/components/waka-address-autocomplete/index.tsx

@@ -0,0 +1,1202 @@
+"use client"
+
+import * as React from "react"
+import {
+  MapPin,
+  Search,
+  X,
+  Clock,
+  Navigation,
+  Loader2,
+  ChevronDown,
+  Building2,
+  Home,
+  Edit3,
+} from "lucide-react"
+import { cn } from "../../utils/cn"
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AddressParts {
+  /** Street address (e.g., "123 Main St") */
+  street: string
+  /** City name */
+  city: string
+  /** State/Province/Region */
+  state?: string
+  /** Postal/ZIP code */
+  zip: string
+  /** Country name */
+  country: string
+  /** Full formatted address */
+  formatted: string
+}
+
+export interface AddressSuggestion {
+  /** Unique identifier */
+  id: string
+  /** Primary address text */
+  primary: string
+  /** Secondary text (city, state, etc.) */
+  secondary: string
+  /** Parsed address parts */
+  parts: AddressParts
+  /** Address type */
+  type?: "home" | "business" | "other"
+  /** Distance from user (if location available) */
+  distance?: string
+}
+
+export interface RecentAddress extends AddressSuggestion {
+  /** Timestamp of last use */
+  lastUsed: Date
+}
+
+export interface WakaAddressAutocompleteProps {
+  /** Selected address value */
+  value?: AddressSuggestion | null
+  /** Callback when address is selected */
+  onChange?: (address: AddressSuggestion | null) => void
+  /** Callback for search queries (for custom/API implementations) */
+  onSearch?: (query: string) => Promise<AddressSuggestion[]>
+  /** Placeholder text */
+  placeholder?: string
+  /** Enable recent addresses feature */
+  showRecentAddresses?: boolean
+  /** Recent addresses list */
+  recentAddresses?: RecentAddress[]
+  /** Callback when address is added to recents */
+  onAddToRecent?: (address: AddressSuggestion) => void
+  /** Enable manual entry fallback */
+  allowManualEntry?: boolean
+  /** Callback when manual entry is requested */
+  onManualEntry?: () => void
+  /** Debounce delay in milliseconds */
+  debounceMs?: number
+  /** Minimum characters before searching */
+  minChars?: number
+  /** Maximum number of suggestions to show */
+  maxSuggestions?: number
+  /** No results message */
+  noResultsMessage?: string
+  /** Loading message */
+  loadingMessage?: string
+  /** Disabled state */
+  disabled?: boolean
+  /** Error state */
+  error?: string
+  /** Additional CSS classes */
+  className?: string
+  /** Input ID for accessibility */
+  id?: string
+  /** Input name for forms */
+  name?: string
+  /** Label text */
+  label?: string
+  /** Required field */
+  required?: boolean
+  /** Auto focus on mount */
+  autoFocus?: boolean
+}
+
+export interface UseAddressAutocompleteOptions {
+  /** Custom search function */
+  onSearch?: (query: string) => Promise<AddressSuggestion[]>
+  /** Debounce delay in milliseconds */
+  debounceMs?: number
+  /** Minimum characters before searching */
+  minChars?: number
+  /** Maximum number of suggestions */
+  maxSuggestions?: number
+  /** Initial recent addresses */
+  initialRecentAddresses?: RecentAddress[]
+  /** Max recent addresses to store */
+  maxRecentAddresses?: number
+  /** Storage key for recent addresses */
+  storageKey?: string
+}
+
+export interface UseAddressAutocompleteReturn {
+  /** Current search query */
+  query: string
+  /** Set search query */
+  setQuery: (query: string) => void
+  /** Suggestions list */
+  suggestions: AddressSuggestion[]
+  /** Loading state */
+  isLoading: boolean
+  /** Error state */
+  error: string | null
+  /** Recent addresses */
+  recentAddresses: RecentAddress[]
+  /** Add address to recents */
+  addToRecent: (address: AddressSuggestion) => void
+  /** Clear recent addresses */
+  clearRecentAddresses: () => void
+  /** Remove specific recent address */
+  removeFromRecent: (id: string) => void
+  /** Search function */
+  search: (query: string) => Promise<void>
+  /** Clear suggestions */
+  clearSuggestions: () => void
+  /** Parse address string to parts */
+  parseAddress: (addressString: string) => AddressParts
+}
+
+// ============================================
+// MOCK DATA & UTILITIES
+// ============================================
+
+const MOCK_ADDRESSES: AddressSuggestion[] = [
+  {
+    id: "1",
+    primary: "123 Main Street",
+    secondary: "New York, NY 10001, USA",
+    type: "home",
+    parts: {
+      street: "123 Main Street",
+      city: "New York",
+      state: "NY",
+      zip: "10001",
+      country: "USA",
+      formatted: "123 Main Street, New York, NY 10001, USA",
+    },
+  },
+  {
+    id: "2",
+    primary: "456 Oak Avenue",
+    secondary: "Los Angeles, CA 90001, USA",
+    type: "business",
+    parts: {
+      street: "456 Oak Avenue",
+      city: "Los Angeles",
+      state: "CA",
+      zip: "90001",
+      country: "USA",
+      formatted: "456 Oak Avenue, Los Angeles, CA 90001, USA",
+    },
+  },
+  {
+    id: "3",
+    primary: "789 Pine Road",
+    secondary: "Chicago, IL 60601, USA",
+    type: "home",
+    parts: {
+      street: "789 Pine Road",
+      city: "Chicago",
+      state: "IL",
+      zip: "60601",
+      country: "USA",
+      formatted: "789 Pine Road, Chicago, IL 60601, USA",
+    },
+  },
+  {
+    id: "4",
+    primary: "321 Elm Boulevard",
+    secondary: "Houston, TX 77001, USA",
+    type: "other",
+    parts: {
+      street: "321 Elm Boulevard",
+      city: "Houston",
+      state: "TX",
+      zip: "77001",
+      country: "USA",
+      formatted: "321 Elm Boulevard, Houston, TX 77001, USA",
+    },
+  },
+  {
+    id: "5",
+    primary: "555 Cedar Lane",
+    secondary: "Phoenix, AZ 85001, USA",
+    type: "home",
+    parts: {
+      street: "555 Cedar Lane",
+      city: "Phoenix",
+      state: "AZ",
+      zip: "85001",
+      country: "USA",
+      formatted: "555 Cedar Lane, Phoenix, AZ 85001, USA",
+    },
+  },
+  {
+    id: "6",
+    primary: "10 Downing Street",
+    secondary: "London, SW1A 2AA, UK",
+    type: "business",
+    parts: {
+      street: "10 Downing Street",
+      city: "London",
+      state: "",
+      zip: "SW1A 2AA",
+      country: "UK",
+      formatted: "10 Downing Street, London, SW1A 2AA, UK",
+    },
+  },
+  {
+    id: "7",
+    primary: "1600 Pennsylvania Avenue",
+    secondary: "Washington, DC 20500, USA",
+    type: "business",
+    parts: {
+      street: "1600 Pennsylvania Avenue",
+      city: "Washington",
+      state: "DC",
+      zip: "20500",
+      country: "USA",
+      formatted: "1600 Pennsylvania Avenue, Washington, DC 20500, USA",
+    },
+  },
+  {
+    id: "8",
+    primary: "350 Fifth Avenue",
+    secondary: "New York, NY 10118, USA",
+    type: "business",
+    distance: "2.3 mi",
+    parts: {
+      street: "350 Fifth Avenue",
+      city: "New York",
+      state: "NY",
+      zip: "10118",
+      country: "USA",
+      formatted: "350 Fifth Avenue, New York, NY 10118, USA",
+    },
+  },
+]
+
+/**
+ * Parse a raw address string into structured parts
+ */
+function parseAddressString(addressString: string): AddressParts {
+  // Simple parsing logic - in production, use a proper address parser
+  const parts = addressString.split(",").map((p) => p.trim())
+
+  const street = parts[0] || ""
+  const cityStateZip = parts[1] || ""
+  const country = parts[parts.length - 1] || ""
+
+  // Try to extract state and zip from cityStateZip
+  const stateZipMatch = cityStateZip.match(/^(.+?)\s+([A-Z]{2})\s+(\d{5}(?:-\d{4})?)$/)
+
+  let city = ""
+  let state = ""
+  let zip = ""
+
+  if (stateZipMatch) {
+    city = stateZipMatch[1]
+    state = stateZipMatch[2]
+    zip = stateZipMatch[3]
+  } else {
+    city = cityStateZip
+  }
+
+  return {
+    street,
+    city,
+    state,
+    zip,
+    country: country !== city ? country : "",
+    formatted: addressString,
+  }
+}
+
+/**
+ * Mock search function for demonstration
+ */
+async function mockSearchAddresses(
+  query: string,
+  maxResults: number = 5
+): Promise<AddressSuggestion[]> {
+  // Simulate network delay
+  await new Promise((resolve) => setTimeout(resolve, 300 + Math.random() * 200))
+
+  if (!query.trim()) return []
+
+  const queryLower = query.toLowerCase()
+
+  const results = MOCK_ADDRESSES.filter(
+    (addr) =>
+      addr.primary.toLowerCase().includes(queryLower) ||
+      addr.secondary.toLowerCase().includes(queryLower) ||
+      addr.parts.city.toLowerCase().includes(queryLower) ||
+      addr.parts.zip.includes(query)
+  ).slice(0, maxResults)
+
+  return results
+}
+
+// ============================================
+// HOOK: useAddressAutocomplete
+// ============================================
+
+export function useAddressAutocomplete(
+  options: UseAddressAutocompleteOptions = {}
+): UseAddressAutocompleteReturn {
+  const {
+    onSearch,
+    debounceMs = 300,
+    minChars = 2,
+    maxSuggestions = 5,
+    initialRecentAddresses = [],
+    maxRecentAddresses = 5,
+    storageKey = "waka-address-recent",
+  } = options
+
+  const [query, setQuery] = React.useState("")
+  const [suggestions, setSuggestions] = React.useState<AddressSuggestion[]>([])
+  const [isLoading, setIsLoading] = React.useState(false)
+  const [error, setError] = React.useState<string | null>(null)
+  const [recentAddresses, setRecentAddresses] = React.useState<RecentAddress[]>(
+    initialRecentAddresses
+  )
+
+  const debounceTimerRef = React.useRef<NodeJS.Timeout | null>(null)
+  const abortControllerRef = React.useRef<AbortController | null>(null)
+
+  // Load recent addresses from storage on mount
+  React.useEffect(() => {
+    if (typeof window === "undefined") return
+
+    try {
+      const stored = localStorage.getItem(storageKey)
+      if (stored) {
+        const parsed = JSON.parse(stored) as RecentAddress[]
+        setRecentAddresses(
+          parsed.map((addr) => ({
+            ...addr,
+            lastUsed: new Date(addr.lastUsed),
+          }))
+        )
+      }
+    } catch {
+      // Ignore storage errors
+    }
+  }, [storageKey])
+
+  // Save recent addresses to storage
+  const saveRecentAddresses = React.useCallback(
+    (addresses: RecentAddress[]) => {
+      if (typeof window === "undefined") return
+
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(addresses))
+      } catch {
+        // Ignore storage errors
+      }
+    },
+    [storageKey]
+  )
+
+  // Search function
+  const search = React.useCallback(
+    async (searchQuery: string) => {
+      if (searchQuery.length < minChars) {
+        setSuggestions([])
+        return
+      }
+
+      // Cancel previous request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort()
+      }
+      abortControllerRef.current = new AbortController()
+
+      setIsLoading(true)
+      setError(null)
+
+      try {
+        const searchFn = onSearch || mockSearchAddresses
+        const results = await searchFn(searchQuery)
+        setSuggestions(results.slice(0, maxSuggestions))
+      } catch (err) {
+        if (err instanceof Error && err.name !== "AbortError") {
+          setError("Failed to search addresses. Please try again.")
+          setSuggestions([])
+        }
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [onSearch, minChars, maxSuggestions]
+  )
+
+  // Debounced search effect
+  React.useEffect(() => {
+    if (debounceTimerRef.current) {
+      clearTimeout(debounceTimerRef.current)
+    }
+
+    if (query.length >= minChars) {
+      debounceTimerRef.current = setTimeout(() => {
+        search(query)
+      }, debounceMs)
+    } else {
+      setSuggestions([])
+    }
+
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current)
+      }
+    }
+  }, [query, debounceMs, minChars, search])
+
+  // Add to recent addresses
+  const addToRecent = React.useCallback(
+    (address: AddressSuggestion) => {
+      setRecentAddresses((prev) => {
+        const filtered = prev.filter((addr) => addr.id !== address.id)
+        const newRecent: RecentAddress = {
+          ...address,
+          lastUsed: new Date(),
+        }
+        const updated = [newRecent, ...filtered].slice(0, maxRecentAddresses)
+        saveRecentAddresses(updated)
+        return updated
+      })
+    },
+    [maxRecentAddresses, saveRecentAddresses]
+  )
+
+  // Clear recent addresses
+  const clearRecentAddresses = React.useCallback(() => {
+    setRecentAddresses([])
+    saveRecentAddresses([])
+  }, [saveRecentAddresses])
+
+  // Remove specific recent address
+  const removeFromRecent = React.useCallback(
+    (id: string) => {
+      setRecentAddresses((prev) => {
+        const updated = prev.filter((addr) => addr.id !== id)
+        saveRecentAddresses(updated)
+        return updated
+      })
+    },
+    [saveRecentAddresses]
+  )
+
+  // Clear suggestions
+  const clearSuggestions = React.useCallback(() => {
+    setSuggestions([])
+    setQuery("")
+  }, [])
+
+  // Parse address utility
+  const parseAddress = React.useCallback((addressString: string): AddressParts => {
+    return parseAddressString(addressString)
+  }, [])
+
+  return {
+    query,
+    setQuery,
+    suggestions,
+    isLoading,
+    error,
+    recentAddresses,
+    addToRecent,
+    clearRecentAddresses,
+    removeFromRecent,
+    search,
+    clearSuggestions,
+    parseAddress,
+  }
+}
+
+// ============================================
+// CSS ANIMATIONS
+// ============================================
+
+const dropdownAnimationStyles = `
+  @keyframes waka-address-dropdown-in {
+    from {
+      opacity: 0;
+      transform: translateY(-8px) scale(0.96);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0) scale(1);
+    }
+  }
+
+  @keyframes waka-address-dropdown-out {
+    from {
+      opacity: 1;
+      transform: translateY(0) scale(1);
+    }
+    to {
+      opacity: 0;
+      transform: translateY(-8px) scale(0.96);
+    }
+  }
+
+  @keyframes waka-address-highlight {
+    0% {
+      background-color: transparent;
+    }
+    50% {
+      background-color: hsl(var(--primary) / 0.1);
+    }
+    100% {
+      background-color: transparent;
+    }
+  }
+
+  @keyframes waka-address-pulse {
+    0%, 100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.5;
+    }
+  }
+
+  .waka-address-dropdown-enter {
+    animation: waka-address-dropdown-in 0.2s ease-out forwards;
+  }
+
+  .waka-address-dropdown-exit {
+    animation: waka-address-dropdown-out 0.15s ease-in forwards;
+  }
+
+  .waka-address-highlight {
+    animation: waka-address-highlight 0.5s ease-out;
+  }
+
+  .waka-address-pulse {
+    animation: waka-address-pulse 1.5s ease-in-out infinite;
+  }
+`
+
+// ============================================
+// SUB-COMPONENTS
+// ============================================
+
+interface SuggestionItemProps {
+  suggestion: AddressSuggestion
+  isHighlighted: boolean
+  onSelect: () => void
+  onMouseEnter: () => void
+}
+
+function SuggestionItem({
+  suggestion,
+  isHighlighted,
+  onSelect,
+  onMouseEnter,
+}: SuggestionItemProps) {
+  const Icon =
+    suggestion.type === "home"
+      ? Home
+      : suggestion.type === "business"
+        ? Building2
+        : MapPin
+
+  return (
+    <button
+      type="button"
+      role="option"
+      aria-selected={isHighlighted}
+      className={cn(
+        "w-full flex items-start gap-3 px-3 py-2.5 text-left transition-colors",
+        "hover:bg-accent focus:bg-accent focus:outline-none",
+        isHighlighted && "bg-accent"
+      )}
+      onClick={onSelect}
+      onMouseEnter={onMouseEnter}
+    >
+      <div
+        className={cn(
+          "flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center",
+          "bg-primary/10 text-primary"
+        )}
+      >
+        <Icon className="w-4 h-4" />
+      </div>
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-foreground truncate">
+          {suggestion.primary}
+        </p>
+        <p className="text-xs text-muted-foreground truncate">
+          {suggestion.secondary}
+        </p>
+      </div>
+      {suggestion.distance && (
+        <span className="flex-shrink-0 text-xs text-muted-foreground">
+          {suggestion.distance}
+        </span>
+      )}
+    </button>
+  )
+}
+
+interface RecentAddressItemProps {
+  address: RecentAddress
+  isHighlighted: boolean
+  onSelect: () => void
+  onRemove: () => void
+  onMouseEnter: () => void
+}
+
+function RecentAddressItem({
+  address,
+  isHighlighted,
+  onSelect,
+  onRemove,
+  onMouseEnter,
+}: RecentAddressItemProps) {
+  return (
+    <div
+      role="option"
+      aria-selected={isHighlighted}
+      className={cn(
+        "flex items-center gap-2 px-3 py-2 transition-colors",
+        "hover:bg-accent",
+        isHighlighted && "bg-accent"
+      )}
+      onMouseEnter={onMouseEnter}
+    >
+      <button
+        type="button"
+        className="flex-1 flex items-start gap-3 text-left focus:outline-none"
+        onClick={onSelect}
+      >
+        <div className="flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center bg-muted text-muted-foreground">
+          <Clock className="w-4 h-4" />
+        </div>
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium text-foreground truncate">
+            {address.primary}
+          </p>
+          <p className="text-xs text-muted-foreground truncate">
+            {address.secondary}
+          </p>
+        </div>
+      </button>
+      <button
+        type="button"
+        className="flex-shrink-0 p-1.5 rounded-md hover:bg-destructive/10 hover:text-destructive transition-colors"
+        onClick={(e) => {
+          e.stopPropagation()
+          onRemove()
+        }}
+        aria-label="Remove from recent"
+      >
+        <X className="w-3.5 h-3.5" />
+      </button>
+    </div>
+  )
+}
+
+interface SelectedAddressDisplayProps {
+  address: AddressSuggestion
+  onClear: () => void
+  onEdit: () => void
+  disabled?: boolean
+}
+
+function SelectedAddressDisplay({
+  address,
+  onClear,
+  onEdit,
+  disabled,
+}: SelectedAddressDisplayProps) {
+  const Icon =
+    address.type === "home"
+      ? Home
+      : address.type === "business"
+        ? Building2
+        : MapPin
+
+  return (
+    <div
+      className={cn(
+        "flex items-start gap-3 p-3 rounded-lg border bg-card",
+        "transition-all duration-200",
+        disabled && "opacity-50 pointer-events-none"
+      )}
+    >
+      <div className="flex-shrink-0 w-10 h-10 rounded-full flex items-center justify-center bg-primary/10 text-primary">
+        <Icon className="w-5 h-5" />
+      </div>
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-foreground">{address.primary}</p>
+        <p className="text-xs text-muted-foreground mt-0.5">
+          {address.secondary}
+        </p>
+        <div className="flex flex-wrap gap-1.5 mt-2">
+          {address.parts.city && (
+            <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs bg-muted text-muted-foreground">
+              {address.parts.city}
+            </span>
+          )}
+          {address.parts.zip && (
+            <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs bg-muted text-muted-foreground">
+              {address.parts.zip}
+            </span>
+          )}
+          {address.parts.country && (
+            <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs bg-muted text-muted-foreground">
+              {address.parts.country}
+            </span>
+          )}
+        </div>
+      </div>
+      <div className="flex-shrink-0 flex items-center gap-1">
+        <button
+          type="button"
+          className="p-1.5 rounded-md hover:bg-accent transition-colors"
+          onClick={onEdit}
+          aria-label="Edit address"
+        >
+          <Edit3 className="w-4 h-4 text-muted-foreground" />
+        </button>
+        <button
+          type="button"
+          className="p-1.5 rounded-md hover:bg-destructive/10 hover:text-destructive transition-colors"
+          onClick={onClear}
+          aria-label="Clear address"
+        >
+          <X className="w-4 h-4" />
+        </button>
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// MAIN COMPONENT
+// ============================================
+
+export const WakaAddressAutocomplete = React.forwardRef<
+  HTMLInputElement,
+  WakaAddressAutocompleteProps
+>(
+  (
+    {
+      value,
+      onChange,
+      onSearch,
+      placeholder = "Search for an address...",
+      showRecentAddresses = true,
+      recentAddresses: externalRecentAddresses,
+      onAddToRecent,
+      allowManualEntry = true,
+      onManualEntry,
+      debounceMs = 300,
+      minChars = 2,
+      maxSuggestions = 5,
+      noResultsMessage = "No addresses found",
+      loadingMessage = "Searching...",
+      disabled = false,
+      error,
+      className,
+      id,
+      name,
+      label,
+      required = false,
+      autoFocus = false,
+    },
+    ref
+  ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null)
+    const dropdownRef = React.useRef<HTMLDivElement>(null)
+    const [isOpen, setIsOpen] = React.useState(false)
+    const [highlightedIndex, setHighlightedIndex] = React.useState(-1)
+    const [isEditing, setIsEditing] = React.useState(!value)
+
+    // Use the hook
+    const {
+      query,
+      setQuery,
+      suggestions,
+      isLoading,
+      error: searchError,
+      recentAddresses: hookRecentAddresses,
+      addToRecent,
+      removeFromRecent,
+    } = useAddressAutocomplete({
+      onSearch,
+      debounceMs,
+      minChars,
+      maxSuggestions,
+    })
+
+    const recentAddresses = externalRecentAddresses ?? hookRecentAddresses
+    const displayError = error || searchError
+
+    // Combined ref
+    React.useImperativeHandle(ref, () => inputRef.current as HTMLInputElement)
+
+    // Inject styles
+    React.useEffect(() => {
+      if (typeof document === "undefined") return
+
+      const styleId = "waka-address-autocomplete-styles"
+      if (!document.getElementById(styleId)) {
+        const style = document.createElement("style")
+        style.id = styleId
+        style.textContent = dropdownAnimationStyles
+        document.head.appendChild(style)
+      }
+    }, [])
+
+    // Calculate what to show in dropdown
+    const showRecent =
+      showRecentAddresses &&
+      recentAddresses.length > 0 &&
+      query.length < minChars
+    const showSuggestions = suggestions.length > 0 && query.length >= minChars
+    const showNoResults =
+      !isLoading &&
+      query.length >= minChars &&
+      suggestions.length === 0
+    const showContent = showRecent || showSuggestions || showNoResults || isLoading
+
+    // All items for keyboard navigation
+    const allItems = React.useMemo(() => {
+      if (showRecent) {
+        return recentAddresses.map((addr) => ({
+          type: "recent" as const,
+          item: addr,
+        }))
+      }
+      if (showSuggestions) {
+        return suggestions.map((addr) => ({
+          type: "suggestion" as const,
+          item: addr,
+        }))
+      }
+      return []
+    }, [showRecent, showSuggestions, recentAddresses, suggestions])
+
+    // Handle selection
+    const handleSelect = React.useCallback(
+      (address: AddressSuggestion) => {
+        onChange?.(address)
+        addToRecent(address)
+        onAddToRecent?.(address)
+        setQuery("")
+        setIsOpen(false)
+        setIsEditing(false)
+        setHighlightedIndex(-1)
+      },
+      [onChange, addToRecent, onAddToRecent, setQuery]
+    )
+
+    // Handle clear
+    const handleClear = React.useCallback(() => {
+      onChange?.(null)
+      setQuery("")
+      setIsEditing(true)
+      inputRef.current?.focus()
+    }, [onChange, setQuery])
+
+    // Handle edit
+    const handleEdit = React.useCallback(() => {
+      setIsEditing(true)
+      setQuery(value?.parts.formatted || "")
+      setTimeout(() => inputRef.current?.focus(), 0)
+    }, [value, setQuery])
+
+    // Handle input change
+    const handleInputChange = React.useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        setQuery(e.target.value)
+        setHighlightedIndex(-1)
+        if (!isOpen) {
+          setIsOpen(true)
+        }
+      },
+      [setQuery, isOpen]
+    )
+
+    // Handle focus
+    const handleFocus = React.useCallback(() => {
+      setIsOpen(true)
+    }, [])
+
+    // Handle blur
+    const handleBlur = React.useCallback((e: React.FocusEvent) => {
+      // Don't close if clicking inside dropdown
+      if (
+        dropdownRef.current &&
+        dropdownRef.current.contains(e.relatedTarget as Node)
+      ) {
+        return
+      }
+      // Delay to allow click events to fire
+      setTimeout(() => setIsOpen(false), 150)
+    }, [])
+
+    // Handle keyboard navigation
+    const handleKeyDown = React.useCallback(
+      (e: React.KeyboardEvent) => {
+        if (!isOpen) {
+          if (e.key === "ArrowDown" || e.key === "Enter") {
+            setIsOpen(true)
+            e.preventDefault()
+          }
+          return
+        }
+
+        switch (e.key) {
+          case "ArrowDown":
+            e.preventDefault()
+            setHighlightedIndex((prev) =>
+              prev < allItems.length - 1 ? prev + 1 : prev
+            )
+            break
+          case "ArrowUp":
+            e.preventDefault()
+            setHighlightedIndex((prev) => (prev > 0 ? prev - 1 : -1))
+            break
+          case "Enter":
+            e.preventDefault()
+            if (highlightedIndex >= 0 && allItems[highlightedIndex]) {
+              handleSelect(allItems[highlightedIndex].item)
+            }
+            break
+          case "Escape":
+            e.preventDefault()
+            setIsOpen(false)
+            setHighlightedIndex(-1)
+            break
+          case "Tab":
+            setIsOpen(false)
+            setHighlightedIndex(-1)
+            break
+        }
+      },
+      [isOpen, allItems, highlightedIndex, handleSelect]
+    )
+
+    // Handle manual entry click
+    const handleManualEntryClick = React.useCallback(() => {
+      onManualEntry?.()
+      setIsOpen(false)
+    }, [onManualEntry])
+
+    // If we have a selected value and not editing, show the display
+    if (value && !isEditing) {
+      return (
+        <div className={cn("space-y-1.5", className)}>
+          {label && (
+            <label
+              htmlFor={id}
+              className="text-sm font-medium text-foreground"
+            >
+              {label}
+              {required && <span className="text-destructive ml-1">*</span>}
+            </label>
+          )}
+          <SelectedAddressDisplay
+            address={value}
+            onClear={handleClear}
+            onEdit={handleEdit}
+            disabled={disabled}
+          />
+          {name && (
+            <input
+              type="hidden"
+              name={name}
+              value={value.parts.formatted}
+            />
+          )}
+        </div>
+      )
+    }
+
+    return (
+      <div className={cn("relative space-y-1.5", className)}>
+        {label && (
+          <label
+            htmlFor={id}
+            className="text-sm font-medium text-foreground"
+          >
+            {label}
+            {required && <span className="text-destructive ml-1">*</span>}
+          </label>
+        )}
+
+        {/* Input container */}
+        <div className="relative">
+          <div className="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none">
+            {isLoading ? (
+              <Loader2 className="w-4 h-4 text-muted-foreground animate-spin" />
+            ) : (
+              <Search className="w-4 h-4 text-muted-foreground" />
+            )}
+          </div>
+          <input
+            ref={inputRef}
+            type="text"
+            id={id}
+            name={name}
+            role="combobox"
+            aria-expanded={isOpen}
+            aria-haspopup="listbox"
+            aria-autocomplete="list"
+            aria-controls={isOpen ? "address-listbox" : undefined}
+            aria-activedescendant={
+              highlightedIndex >= 0
+                ? `address-option-${highlightedIndex}`
+                : undefined
+            }
+            autoComplete="off"
+            autoFocus={autoFocus}
+            disabled={disabled}
+            required={required}
+            placeholder={placeholder}
+            value={query}
+            onChange={handleInputChange}
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            onKeyDown={handleKeyDown}
+            className={cn(
+              "flex h-10 w-full rounded-md border border-input bg-background",
+              "pl-10 pr-10 py-2 text-sm",
+              "ring-offset-background",
+              "placeholder:text-muted-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+              "disabled:cursor-not-allowed disabled:opacity-50",
+              "transition-colors",
+              displayError && "border-destructive focus-visible:ring-destructive"
+            )}
+          />
+          <div className="absolute inset-y-0 right-0 flex items-center pr-2">
+            {query && (
+              <button
+                type="button"
+                className="p-1 rounded-md hover:bg-accent transition-colors"
+                onClick={() => {
+                  setQuery("")
+                  inputRef.current?.focus()
+                }}
+                aria-label="Clear search"
+              >
+                <X className="w-4 h-4 text-muted-foreground" />
+              </button>
+            )}
+            <button
+              type="button"
+              className="p-1 rounded-md hover:bg-accent transition-colors"
+              onClick={() => setIsOpen(!isOpen)}
+              aria-label="Toggle dropdown"
+            >
+              <ChevronDown
+                className={cn(
+                  "w-4 h-4 text-muted-foreground transition-transform duration-200",
+                  isOpen && "rotate-180"
+                )}
+              />
+            </button>
+          </div>
+        </div>
+
+        {/* Error message */}
+        {displayError && (
+          <p className="text-sm text-destructive">{displayError}</p>
+        )}
+
+        {/* Dropdown */}
+        {isOpen && showContent && (
+          <div
+            ref={dropdownRef}
+            id="address-listbox"
+            role="listbox"
+            className={cn(
+              "absolute z-50 w-full mt-1 py-1 rounded-md border bg-popover shadow-lg",
+              "waka-address-dropdown-enter"
+            )}
+          >
+            {/* Loading state */}
+            {isLoading && (
+              <div className="flex items-center justify-center gap-2 py-6 text-sm text-muted-foreground">
+                <Loader2 className="w-4 h-4 animate-spin" />
+                <span>{loadingMessage}</span>
+              </div>
+            )}
+
+            {/* Recent addresses */}
+            {showRecent && !isLoading && (
+              <div>
+                <div className="px-3 py-2 text-xs font-medium text-muted-foreground uppercase tracking-wider">
+                  Recent Addresses
+                </div>
+                {recentAddresses.map((address, index) => (
+                  <RecentAddressItem
+                    key={address.id}
+                    address={address}
+                    isHighlighted={highlightedIndex === index}
+                    onSelect={() => handleSelect(address)}
+                    onRemove={() => removeFromRecent(address.id)}
+                    onMouseEnter={() => setHighlightedIndex(index)}
+                  />
+                ))}
+              </div>
+            )}
+
+            {/* Suggestions */}
+            {showSuggestions && !isLoading && (
+              <div>
+                <div className="px-3 py-2 text-xs font-medium text-muted-foreground uppercase tracking-wider">
+                  Suggestions
+                </div>
+                {suggestions.map((suggestion, index) => (
+                  <SuggestionItem
+                    key={suggestion.id}
+                    suggestion={suggestion}
+                    isHighlighted={highlightedIndex === index}
+                    onSelect={() => handleSelect(suggestion)}
+                    onMouseEnter={() => setHighlightedIndex(index)}
+                  />
+                ))}
+              </div>
+            )}
+
+            {/* No results */}
+            {showNoResults && (
+              <div className="py-6 text-center">
+                <Navigation className="w-8 h-8 mx-auto text-muted-foreground/50 mb-2" />
+                <p className="text-sm text-muted-foreground">{noResultsMessage}</p>
+                {allowManualEntry && onManualEntry && (
+                  <button
+                    type="button"
+                    className="mt-2 text-sm text-primary hover:underline"
+                    onClick={handleManualEntryClick}
+                  >
+                    Enter address manually
+                  </button>
+                )}
+              </div>
+            )}
+
+            {/* Manual entry option (when showing recent/suggestions) */}
+            {allowManualEntry && onManualEntry && !showNoResults && !isLoading && (
+              <div className="border-t mt-1 pt-1">
+                <button
+                  type="button"
+                  className="w-full flex items-center gap-2 px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+                  onClick={handleManualEntryClick}
+                >
+                  <Edit3 className="w-4 h-4" />
+                  <span>Enter address manually</span>
+                </button>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    )
+  }
+)
+
+WakaAddressAutocomplete.displayName = "WakaAddressAutocomplete"
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export default WakaAddressAutocomplete