郵便番号APIが返す複数候補をどう扱うか

GET https://zipcloud.ibsnet.co.jp/api/search?zipcode=0600000
→ address1: 北海道 / address2: 札幌市中央区 / address3: ""（空文字列）

// src/lib/postal-code/town.ts
 
/**
 * 日本郵便の郵便番号データで、町域名の位置に入る特殊表記。
 * 住所として連結してはいけない。
 */
const NON_TOWN_PATTERNS: readonly RegExp[] = [
  /^以下に掲載がない場合$/,
  /^.+?[市町村]の次に番地がくる場合$/,
  /^.+?[市町村]一円$/,
]
 
/** 町域名として住所に連結してよい文字列かどうか。 */
export function isUsableTownName(town: string): boolean {
  const trimmed = town.trim()
  if (trimmed === '') return false
  return !NON_TOWN_PATTERNS.some((pattern) => pattern.test(trimmed))
}

// src/lib/postal-code/candidate.ts
import { isUsableTownName } from './town'
 
export type Candidate = {
  prefecture: string
  city: string
  /** 特殊表記だった場合は空文字。住所欄に連結してはいけない。 */
  town: string
}
 
type ApiResult = {
  address1: string
  address2: string
  address3: string
}
 
export function toCandidate(result: ApiResult): Candidate {
  const town = result.address3.trim()
  return {
    prefecture: result.address1.trim(),
    city: result.address2.trim(),
    town: isUsableTownName(town) ? town : '',
  }
}

// src/lib/postal-code/candidate.ts（続き）
 
function candidateKey(candidate: Candidate): string {
  return `${candidate.prefecture}�${candidate.city}�${candidate.town}`
}
 
/** 表示順を保ったまま、完全に同じ候補を1件にまとめる。 */
export function dedupeCandidates(candidates: Candidate[]): Candidate[] {
  const seen = new Set<string>()
  const result: Candidate[] = []
 
  for (const candidate of candidates) {
    const key = candidateKey(candidate)
    if (seen.has(key)) continue
    seen.add(key)
    result.push(candidate)
  }
 
  return result
}

// src/lib/postal-code/decide.ts
import type { Candidate } from './candidate'
 
export type LookupOutcome =
  | { kind: 'empty' }
  | { kind: 'autofill'; candidate: Candidate }
  | { kind: 'choose'; candidates: Candidate[] }
 
export function decideOutcome(candidates: Candidate[]): LookupOutcome {
  if (candidates.length === 0) return { kind: 'empty' }
 
  const [first] = candidates
  if (candidates.length === 1 && first) {
    // 町域が空でも自動入力する。都道府県・市区町村までは確定しているため。
    return { kind: 'autofill', candidate: first }
  }
 
  return { kind: 'choose', candidates }
}

// 候補の選択部分のみ抜粋
type Props = {
  candidates: { prefecture: string; city: string; town: string }[]
  onSelect: (index: number) => void
}
 
export function CandidateChoice({ candidates, onSelect }: Props) {
  return (
    <fieldset>
      <legend>住所を選んでください（{candidates.length}件）</legend>
      {candidates.map((candidate, index) => {
        const label =
          `${candidate.prefecture}${candidate.city}${candidate.town}` ||
          `${candidate.prefecture}${candidate.city}`
        return (
          <label key={label} htmlFor={`candidate-${index}`}>
            <input
              type="radio"
              id={`candidate-${index}`}
              name="address-candidate"
              value={index}
              onChange={() => onSelect(index)}
            />
            {label}
          </label>
        )
      })}
    </fieldset>
  )
}

// 避けたい形：連結済みの1本の文字列だけを持つ
type BadRecord = { address: string }
 
// 望ましい形：要素を分けて持ち、由来も残す
type AddressRecord = {
  postalCode: string
  prefecture: string
  city: string
  town: string
  /** 番地・建物名。APIは返さないので、必ずユーザー入力。 */
  addressLine: string
  /** 自動入力か手入力かを残しておく。 */
  source: 'postal-code-api' | 'manual'
}