@cp949/japanpost-react 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -1,11 +1 @@
-export { AddressSearchInput } from './components/AddressSearchInput';
-export { PostalCodeInput } from './components/PostalCodeInput';
-export { createJapanAddressError } from './core/errors';
-export { formatJapanPostalCode, normalizeJapanPostalCode, } from './core/formatters';
-export { normalizeJapanPostAddressRecord } from './core/normalizers';
-export type { AddressSearchInputProps, JapanAddress, JapanAddressDataSource, JapanAddressError, JapanAddressErrorCode, JapanAddressRequestOptions, JapanAddressSearchResult, JapanPostalCodeLookupResult, NormalizedJapanAddressRecord, PostalCodeInputProps, UseJapanAddressOptions, UseJapanAddressResult, UseJapanAddressSearchOptions, UseJapanAddressSearchResult, UseJapanPostalCodeOptions, UseJapanPostalCodeResult, } from './core/types';
-export { isValidJapanPostalCode } from './core/validators';
-export { useJapanAddress } from './react/useJapanAddress';
-export { useJapanAddressSearch } from './react/useJapanAddressSearch';
-export { useJapanPostalCode } from './react/useJapanPostalCode';
-//# sourceMappingURL=index.d.ts.map
+export {}

package/dist/index.es.js

@@ -283,31 +283,36 @@ function y() {
 	let n = r(0), a = r(!0), o = r(null), [s, c] = i(!1), [l, u] = i(null), [d, f] = i(null), p = e((e) => a.current && e === n.current, []), m = e(() => {
 		n.current += 1, o.current?.abort(), o.current = null;
 	}, []);
-	return t(() => (a.current = !0, () => {
+	t(() => (a.current = !0, () => {
 		a.current = !1, m();
-	}), [m]), {
+	}), [m]);
+	let h = e(() => {
+		let e = n.current + 1;
+		n.current = e, o.current?.abort();
+		let t = new AbortController();
+		return o.current = t, c(!0), f(null), {
+			requestId: e,
+			signal: t.signal
+		};
+	}, []), g = e((e, t) => {
+		p(e) && u(t);
+	}, [p]), _ = e((e, t) => (p(e) && (f(t), u(null)), null), [p]), v = e(() => {
+		m(), c(!1);
+	}, [m]);
+	return {
 		loading: s,
 		data: l,
 		error: d,
-		beginRequest: e(() => {
-			let e = n.current + 1;
-			n.current = e, o.current?.abort();
-			let t = new AbortController();
-			return o.current = t, c(!0), f(null), {
-				requestId: e,
-				signal: t.signal
-			};
-		}, []),
-		setSuccess: e((e, t) => {
-			p(e) && u(t);
-		}, [p]),
-		setFailure: e((e, t) => (p(e) && (f(t), u(null)), null), [p]),
+		beginRequest: h,
+		setSuccess: g,
+		setFailure: _,
 		finishRequest: e((e) => {
 			p(e) && (c(!1), o.current = null);
 		}, [p]),
+		cancel: v,
 		reset: e(() => {
-			m(), c(!1), u(null), f(null);
-		}, [m])
+			v(), u(null), f(null);
+		}, [v])
 	};
 }
 //#endregion
@@ -316,26 +321,55 @@ function b(e) {
 	if (e) return e;
 	throw Error("useJapanAddressSearch requires options.dataSource");
 }
-function x(i) {
-	let a = n(() => b(i.dataSource), [i.dataSource]), o = i.debounceMs ?? 0, s = r(null), c = r(null), { loading: l, data: u, error: d, beginRequest: f, setSuccess: p, setFailure: h, finishRequest: g, reset: _ } = y(), x = e((e) => {
+function x(e) {
+	return e?.trim() || void 0;
+}
+function S(e) {
+	let t = typeof e == "string" ? { addressQuery: e } : e, n = x(t.addressQuery), r = x(t.prefCode), i = x(t.prefName), a = x(t.prefKana), o = x(t.prefRoma), s = x(t.cityCode), c = x(t.cityName), l = x(t.cityKana), u = x(t.cityRoma), d = x(t.townName), f = x(t.townKana), p = x(t.townRoma);
+	return n === void 0 && r === void 0 && i === void 0 && a === void 0 && o === void 0 && s === void 0 && c === void 0 && l === void 0 && u === void 0 && d === void 0 && f === void 0 && p === void 0 ? null : {
+		...n === void 0 ? {} : { addressQuery: n },
+		...r === void 0 ? {} : { prefCode: r },
+		...i === void 0 ? {} : { prefName: i },
+		...a === void 0 ? {} : { prefKana: a },
+		...o === void 0 ? {} : { prefRoma: o },
+		...s === void 0 ? {} : { cityCode: s },
+		...c === void 0 ? {} : { cityName: c },
+		...l === void 0 ? {} : { cityKana: l },
+		...u === void 0 ? {} : { cityRoma: u },
+		...d === void 0 ? {} : { townName: d },
+		...f === void 0 ? {} : { townKana: f },
+		...p === void 0 ? {} : { townRoma: p },
+		pageNumber: t.pageNumber ?? 0,
+		rowsPerPage: t.rowsPerPage ?? 100,
+		...t.includeCityDetails === void 0 ? {} : { includeCityDetails: t.includeCityDetails },
+		...t.includePrefectureDetails === void 0 ? {} : { includePrefectureDetails: t.includePrefectureDetails }
+	};
+}
+function C(e) {
+	return e.aborted ? Promise.resolve(null) : new Promise((t) => {
+		let n = () => {
+			e.removeEventListener("abort", n), t(null);
+		};
+		e.addEventListener("abort", n, { once: !0 });
+	});
+}
+function w(i) {
+	let a = n(() => b(i.dataSource), [i.dataSource]), o = i.debounceMs ?? 0, s = r(null), c = r(null), { loading: l, data: u, error: d, beginRequest: f, setSuccess: p, setFailure: h, finishRequest: g, cancel: _, reset: x } = y(), w = e((e) => {
 		s.current !== null && (globalThis.clearTimeout(s.current), s.current = null), c.current?.(e), c.current = null;
 	}, []);
 	t(() => () => {
-		x(null);
-	}, [x]);
-	let S = e(() => {
-		x(null), _();
-	}, [x, _]), C = e(async (e, t, n) => {
+		w(null);
+	}, [w]);
+	let T = e(() => {
+		w(null), x();
+	}, [w, x]), E = e(() => {
+		w(null), _();
+	}, [w, _]), D = e(async (e, t, n) => {
 		try {
-			let r = n.trim();
-			if (!r) throw m("invalid_query", "Address query is required");
-			let i = { signal: t }, o = {
-				query: r,
-				addresses: await a.searchAddress(r, i)
-			};
-			return p(e, o), o;
-		} catch (t) {
-			return h(e, v(t));
+			let r = { signal: t }, i = a.searchAddress(n, r), o = await Promise.race([i, C(t)]);
+			return t.aborted || o === null ? null : (p(e, o), o);
+		} catch (n) {
+			return t.aborted ? null : h(e, v(n));
 		} finally {
 			g(e);
 		}
@@ -349,51 +383,63 @@ function x(i) {
 		loading: l,
 		data: u,
 		error: d,
-		reset: S,
+		cancel: E,
+		reset: T,
 		search: e((e) => {
-			let { requestId: t, signal: n } = f();
-			return x(null), o <= 0 ? C(t, n, e) : new Promise((r) => {
-				c.current = r, s.current = globalThis.setTimeout(() => {
+			let t = S(e), { requestId: n, signal: r } = f();
+			if (w(null), t === null) {
+				let e = h(n, m("invalid_query", "Address query is required"));
+				return g(n), Promise.resolve(e);
+			}
+			return o <= 0 ? new Promise((e) => {
+				c.current = e, D(n, r, t).then((t) => {
+					e(t), c.current === e && (c.current = null);
+				});
+			}) : new Promise((e) => {
+				c.current = e, s.current = globalThis.setTimeout(() => {
 					s.current = null;
-					let r = c.current;
-					c.current = null, C(t, n, e).then((e) => {
-						r?.(e);
+					let e = c.current;
+					c.current = null, D(n, r, t).then((t) => {
+						e?.(t);
 					});
 				}, o);
 			});
 		}, [
 			f,
-			x,
+			w,
 			o,
-			C
+			D
 		])
 	};
 }
 //#endregion
 //#region src/react/useJapanPostalCode.ts
-function S(e) {
+function T(e) {
 	if (e) return e;
 	throw Error("useJapanPostalCode requires options.dataSource");
 }
-function C(t) {
-	let r = n(() => S(t.dataSource), [t.dataSource]), { loading: i, data: a, error: o, beginRequest: s, setSuccess: c, setFailure: l, finishRequest: u, reset: f } = y();
+function E(t) {
+	let r = n(() => T(t.dataSource), [t.dataSource]), { loading: i, data: a, error: o, beginRequest: s, setSuccess: c, setFailure: l, finishRequest: u, cancel: f, reset: p } = y();
 	return {
 		loading: i,
 		data: a,
 		error: o,
-		reset: f,
+		cancel: f,
+		reset: p,
 		search: e(async (e) => {
 			let { requestId: t, signal: n } = s();
 			try {
-				let i = d(e);
-				if (!/^\d{7}$/.test(i)) throw m("invalid_postal_code", "Postal code must contain exactly 7 digits");
-				let a = { signal: n }, o = {
-					postalCode: i,
-					addresses: await r.lookupPostalCode(i, a)
-				};
-				return c(t, o), o;
+				let i = typeof e == "string" ? { postalCode: e } : e, a = d(i.postalCode);
+				if (!/^\d{3,7}$/.test(a)) throw m("invalid_postal_code", "Postal code must contain between 3 and 7 digits");
+				let o = { signal: n }, s = {
+					postalCode: a,
+					pageNumber: i.pageNumber ?? 0,
+					rowsPerPage: i.rowsPerPage ?? 100,
+					...i.includeParenthesesTown === void 0 ? {} : { includeParenthesesTown: i.includeParenthesesTown }
+				}, l = await r.lookupPostalCode(s, o);
+				return n.aborted ? null : (c(t, l), l);
 			} catch (e) {
-				return l(t, v(e));
+				return n.aborted ? null : l(t, v(e));
 			} finally {
 				u(t);
 			}
@@ -408,24 +454,24 @@ function C(t) {
 }
 //#endregion
 //#region src/react/useJapanAddress.ts
-function w(t) {
+function D(t) {
 	let r = n(() => {
 		if (t.dataSource) return t.dataSource;
 		throw Error("useJapanAddress requires options.dataSource");
-	}, [t.dataSource]), a = C({ dataSource: r }), o = x({
+	}, [t.dataSource]), a = E({ dataSource: r }), o = w({
 		dataSource: r,
 		debounceMs: t.debounceMs
-	}), s = a.reset, c = a.search, l = o.reset, u = o.search, [d, f] = i(null), p = e(async (e) => (l(), f("postalCode"), c(e)), [l, c]), m = e(async (e) => (s(), f("keyword"), u(e)), [s, u]), h = e(() => {
+	}), s = a.reset, c = a.search, l = o.reset, u = o.search, [d, f] = i(null), p = e(async (e) => (l(), f("postalCode"), c(e)), [l, c]), m = e(async (e) => (s(), f("addressQuery"), u(e)), [s, u]), h = e(() => {
 		s(), l(), f(null);
-	}, [l, s]), g = d === "postalCode" ? a.data : d === "keyword" ? o.data : null, _ = d === "postalCode" ? a.error : d === "keyword" ? o.error : null;
+	}, [l, s]), g = d === "postalCode" ? a.data : d === "addressQuery" ? o.data : null, _ = d === "postalCode" ? a.error : d === "addressQuery" ? o.error : null;
 	return {
 		loading: a.loading || o.loading,
 		data: g,
 		error: _,
 		reset: h,
 		searchByPostalCode: p,
-		searchByKeyword: m
+		searchByAddressQuery: m
 	};
 }
 //#endregion
-export { u as AddressSearchInput, p as PostalCodeInput, m as createJapanAddressError, f as formatJapanPostalCode, _ as isValidJapanPostalCode, g as normalizeJapanPostAddressRecord, d as normalizeJapanPostalCode, w as useJapanAddress, x as useJapanAddressSearch, C as useJapanPostalCode };
+export { u as AddressSearchInput, p as PostalCodeInput, m as createJapanAddressError, f as formatJapanPostalCode, _ as isValidJapanPostalCode, g as normalizeJapanPostAddressRecord, d as normalizeJapanPostalCode, D as useJapanAddress, w as useJapanAddressSearch, E as useJapanPostalCode };

package/dist/index.umd.cjs

@@ -3,4 +3,4 @@
   <%s {...props} />
 React keys must be passed directly to JSX without using spread:
   let props = %s;
-  <%s key={someKey} {...props} />`,o,p,m,p),L[p+o]=!0)}if(p=null,i!==void 0&&(r(i),p=``+i),s(n)&&(r(n.key),p=``+n.key),`key`in n)for(var h in i={},n)h!==`key`&&(i[h]=n[h]);else i=n;return p&&c(i,typeof e==`function`?e.displayName||e.name||`Unknown`:e),u(e,p,i,a(),l,d)}function f(e){p(e)?e._store&&(e._store.validated=1):typeof e==`object`&&e&&e.$$typeof===E&&(e._payload.status===`fulfilled`?p(e._payload.value)&&e._payload.value._store&&(e._payload.value._store.validated=1):e._store&&(e._store.validated=1))}function p(e){return typeof e==`object`&&!!e&&e.$$typeof===h}var m=require(`react`),h=Symbol.for(`react.transitional.element`),g=Symbol.for(`react.portal`),_=Symbol.for(`react.fragment`),v=Symbol.for(`react.strict_mode`),y=Symbol.for(`react.profiler`),b=Symbol.for(`react.consumer`),x=Symbol.for(`react.context`),S=Symbol.for(`react.forward_ref`),C=Symbol.for(`react.suspense`),w=Symbol.for(`react.suspense_list`),T=Symbol.for(`react.memo`),E=Symbol.for(`react.lazy`),D=Symbol.for(`react.activity`),O=Symbol.for(`react.client.reference`),k=m.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,A=Object.prototype.hasOwnProperty,j=Array.isArray,M=console.createTask?console.createTask:function(){return null};m={react_stack_bottom_frame:function(e){return e()}};var N,P={},F=m.react_stack_bottom_frame.bind(m,o)(),I=M(i(o)),L={};e.Fragment=_,e.jsx=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!1,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)},e.jsxs=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!0,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)}})()})),a=n(((e,t)=>{process.env.NODE_ENV===`production`?t.exports=r():t.exports=i()}))();function o({defaultValue:e=``,value:n,disabled:r,label:i=`Address keyword`,buttonLabel:o=`Search`,inputProps:s,buttonProps:c,onChange:l,onSearch:u}){let[d,f]=(0,t.useState)(e),p=n??d;function m(e){e.preventDefault(),u(p.trim())}function h(e){n===void 0&&f(e),l?.(e)}return(0,a.jsxs)(`form`,{onSubmit:m,children:[(0,a.jsxs)(`label`,{children:[i,(0,a.jsx)(`input`,{...s,disabled:r,value:p,onChange:e=>h(e.target.value)})]}),(0,a.jsx)(`button`,{...c,disabled:r,type:`submit`,children:o})]})}function s(e){return e.replace(/[^\d]/g,``)}function c(e){let t=s(e);return t.length===7?`${t.slice(0,3)}-${t.slice(3)}`:t}function l({defaultValue:e=``,value:n,disabled:r,label:i=`Postal code`,buttonLabel:o=`Search`,inputProps:c,buttonProps:l,onChange:u,onSearch:d}){let[f,p]=(0,t.useState)(e),m=n??f;function h(e){e.preventDefault(),d(s(m))}function g(e){n===void 0&&p(e),u?.(e)}return(0,a.jsxs)(`form`,{onSubmit:h,children:[(0,a.jsxs)(`label`,{children:[i,(0,a.jsx)(`input`,{...c,disabled:r,inputMode:c?.inputMode??`numeric`,value:m,onChange:e=>g(e.target.value)})]}),(0,a.jsx)(`button`,{...l,disabled:r,type:`submit`,children:o})]})}function u(e,t,n){let r=Error(t);return r.name=`JapanAddressError`,r.code=e,r.cause=n?.cause,r.status=n?.status,r}function d(e){return e.filter(Boolean).join(` `).trim()}function f(e){let t=d([e.prefecture,e.city,e.town,e.detail??``]);return{postalCode:e.postalCode,prefecture:e.prefecture,prefectureKana:e.prefectureKana,city:e.city,cityKana:e.cityKana,town:e.town,townKana:e.townKana,address:t,provider:`japan-post`}}function p(e){return/^\d{7}$/.test(s(e))}function m(e){return typeof e==`object`&&e&&`code`in e&&typeof e.code==`string`?e:u(`data_source_error`,e instanceof Error?e.message:`Unknown error`,{cause:e})}function h(){let e=(0,t.useRef)(0),n=(0,t.useRef)(!0),r=(0,t.useRef)(null),[i,a]=(0,t.useState)(!1),[o,s]=(0,t.useState)(null),[c,l]=(0,t.useState)(null),u=(0,t.useCallback)(t=>n.current&&t===e.current,[]),d=(0,t.useCallback)(()=>{e.current+=1,r.current?.abort(),r.current=null},[]);return(0,t.useEffect)(()=>(n.current=!0,()=>{n.current=!1,d()}),[d]),{loading:i,data:o,error:c,beginRequest:(0,t.useCallback)(()=>{let t=e.current+1;e.current=t,r.current?.abort();let n=new AbortController;return r.current=n,a(!0),l(null),{requestId:t,signal:n.signal}},[]),setSuccess:(0,t.useCallback)((e,t)=>{u(e)&&s(t)},[u]),setFailure:(0,t.useCallback)((e,t)=>(u(e)&&(l(t),s(null)),null),[u]),finishRequest:(0,t.useCallback)(e=>{u(e)&&(a(!1),r.current=null)},[u]),reset:(0,t.useCallback)(()=>{d(),a(!1),s(null),l(null)},[d])}}function g(e){if(e)return e;throw Error(`useJapanAddressSearch requires options.dataSource`)}function _(e){let n=(0,t.useMemo)(()=>g(e.dataSource),[e.dataSource]),r=e.debounceMs??0,i=(0,t.useRef)(null),a=(0,t.useRef)(null),{loading:o,data:s,error:c,beginRequest:l,setSuccess:d,setFailure:f,finishRequest:p,reset:_}=h(),v=(0,t.useCallback)(e=>{i.current!==null&&(globalThis.clearTimeout(i.current),i.current=null),a.current?.(e),a.current=null},[]);(0,t.useEffect)(()=>()=>{v(null)},[v]);let y=(0,t.useCallback)(()=>{v(null),_()},[v,_]),b=(0,t.useCallback)(async(e,t,r)=>{try{let i=r.trim();if(!i)throw u(`invalid_query`,`Address query is required`);let a={signal:t},o={query:i,addresses:await n.searchAddress(i,a)};return d(e,o),o}catch(t){return f(e,m(t))}finally{p(e)}},[n,p,f,d]);return{loading:o,data:s,error:c,reset:y,search:(0,t.useCallback)(e=>{let{requestId:t,signal:n}=l();return v(null),r<=0?b(t,n,e):new Promise(o=>{a.current=o,i.current=globalThis.setTimeout(()=>{i.current=null;let r=a.current;a.current=null,b(t,n,e).then(e=>{r?.(e)})},r)})},[l,v,r,b])}}function v(e){if(e)return e;throw Error(`useJapanPostalCode requires options.dataSource`)}function y(e){let n=(0,t.useMemo)(()=>v(e.dataSource),[e.dataSource]),{loading:r,data:i,error:a,beginRequest:o,setSuccess:c,setFailure:l,finishRequest:d,reset:f}=h();return{loading:r,data:i,error:a,reset:f,search:(0,t.useCallback)(async e=>{let{requestId:t,signal:r}=o();try{let i=s(e);if(!/^\d{7}$/.test(i))throw u(`invalid_postal_code`,`Postal code must contain exactly 7 digits`);let a={signal:r},o={postalCode:i,addresses:await n.lookupPostalCode(i,a)};return c(t,o),o}catch(e){return l(t,m(e))}finally{d(t)}},[o,n,d,l,c])}}function b(e){let n=(0,t.useMemo)(()=>{if(e.dataSource)return e.dataSource;throw Error(`useJapanAddress requires options.dataSource`)},[e.dataSource]),r=y({dataSource:n}),i=_({dataSource:n,debounceMs:e.debounceMs}),a=r.reset,o=r.search,s=i.reset,c=i.search,[l,u]=(0,t.useState)(null),d=(0,t.useCallback)(async e=>(s(),u(`postalCode`),o(e)),[s,o]),f=(0,t.useCallback)(async e=>(a(),u(`keyword`),c(e)),[a,c]),p=(0,t.useCallback)(()=>{a(),s(),u(null)},[s,a]),m=l===`postalCode`?r.data:l===`keyword`?i.data:null,h=l===`postalCode`?r.error:l===`keyword`?i.error:null;return{loading:r.loading||i.loading,data:m,error:h,reset:p,searchByPostalCode:d,searchByKeyword:f}}e.AddressSearchInput=o,e.PostalCodeInput=l,e.createJapanAddressError=u,e.formatJapanPostalCode=c,e.isValidJapanPostalCode=p,e.normalizeJapanPostAddressRecord=f,e.normalizeJapanPostalCode=s,e.useJapanAddress=b,e.useJapanAddressSearch=_,e.useJapanPostalCode=y});
+  <%s key={someKey} {...props} />`,o,p,m,p),L[p+o]=!0)}if(p=null,i!==void 0&&(r(i),p=``+i),s(n)&&(r(n.key),p=``+n.key),`key`in n)for(var h in i={},n)h!==`key`&&(i[h]=n[h]);else i=n;return p&&c(i,typeof e==`function`?e.displayName||e.name||`Unknown`:e),u(e,p,i,a(),l,d)}function f(e){p(e)?e._store&&(e._store.validated=1):typeof e==`object`&&e&&e.$$typeof===E&&(e._payload.status===`fulfilled`?p(e._payload.value)&&e._payload.value._store&&(e._payload.value._store.validated=1):e._store&&(e._store.validated=1))}function p(e){return typeof e==`object`&&!!e&&e.$$typeof===h}var m=require(`react`),h=Symbol.for(`react.transitional.element`),g=Symbol.for(`react.portal`),_=Symbol.for(`react.fragment`),v=Symbol.for(`react.strict_mode`),y=Symbol.for(`react.profiler`),b=Symbol.for(`react.consumer`),x=Symbol.for(`react.context`),S=Symbol.for(`react.forward_ref`),C=Symbol.for(`react.suspense`),w=Symbol.for(`react.suspense_list`),T=Symbol.for(`react.memo`),E=Symbol.for(`react.lazy`),D=Symbol.for(`react.activity`),O=Symbol.for(`react.client.reference`),k=m.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,A=Object.prototype.hasOwnProperty,j=Array.isArray,M=console.createTask?console.createTask:function(){return null};m={react_stack_bottom_frame:function(e){return e()}};var N,P={},F=m.react_stack_bottom_frame.bind(m,o)(),I=M(i(o)),L={};e.Fragment=_,e.jsx=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!1,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)},e.jsxs=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!0,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)}})()})),a=n(((e,t)=>{process.env.NODE_ENV===`production`?t.exports=r():t.exports=i()}))();function o({defaultValue:e=``,value:n,disabled:r,label:i=`Address keyword`,buttonLabel:o=`Search`,inputProps:s,buttonProps:c,onChange:l,onSearch:u}){let[d,f]=(0,t.useState)(e),p=n??d;function m(e){e.preventDefault(),u(p.trim())}function h(e){n===void 0&&f(e),l?.(e)}return(0,a.jsxs)(`form`,{onSubmit:m,children:[(0,a.jsxs)(`label`,{children:[i,(0,a.jsx)(`input`,{...s,disabled:r,value:p,onChange:e=>h(e.target.value)})]}),(0,a.jsx)(`button`,{...c,disabled:r,type:`submit`,children:o})]})}function s(e){return e.replace(/[^\d]/g,``)}function c(e){let t=s(e);return t.length===7?`${t.slice(0,3)}-${t.slice(3)}`:t}function l({defaultValue:e=``,value:n,disabled:r,label:i=`Postal code`,buttonLabel:o=`Search`,inputProps:c,buttonProps:l,onChange:u,onSearch:d}){let[f,p]=(0,t.useState)(e),m=n??f;function h(e){e.preventDefault(),d(s(m))}function g(e){n===void 0&&p(e),u?.(e)}return(0,a.jsxs)(`form`,{onSubmit:h,children:[(0,a.jsxs)(`label`,{children:[i,(0,a.jsx)(`input`,{...c,disabled:r,inputMode:c?.inputMode??`numeric`,value:m,onChange:e=>g(e.target.value)})]}),(0,a.jsx)(`button`,{...l,disabled:r,type:`submit`,children:o})]})}function u(e,t,n){let r=Error(t);return r.name=`JapanAddressError`,r.code=e,r.cause=n?.cause,r.status=n?.status,r}function d(e){return e.filter(Boolean).join(` `).trim()}function f(e){let t=d([e.prefecture,e.city,e.town,e.detail??``]);return{postalCode:e.postalCode,prefecture:e.prefecture,prefectureKana:e.prefectureKana,city:e.city,cityKana:e.cityKana,town:e.town,townKana:e.townKana,address:t,provider:`japan-post`}}function p(e){return/^\d{7}$/.test(s(e))}function m(e){return typeof e==`object`&&e&&`code`in e&&typeof e.code==`string`?e:u(`data_source_error`,e instanceof Error?e.message:`Unknown error`,{cause:e})}function h(){let e=(0,t.useRef)(0),n=(0,t.useRef)(!0),r=(0,t.useRef)(null),[i,a]=(0,t.useState)(!1),[o,s]=(0,t.useState)(null),[c,l]=(0,t.useState)(null),u=(0,t.useCallback)(t=>n.current&&t===e.current,[]),d=(0,t.useCallback)(()=>{e.current+=1,r.current?.abort(),r.current=null},[]);(0,t.useEffect)(()=>(n.current=!0,()=>{n.current=!1,d()}),[d]);let f=(0,t.useCallback)(()=>{let t=e.current+1;e.current=t,r.current?.abort();let n=new AbortController;return r.current=n,a(!0),l(null),{requestId:t,signal:n.signal}},[]),p=(0,t.useCallback)((e,t)=>{u(e)&&s(t)},[u]),m=(0,t.useCallback)((e,t)=>(u(e)&&(l(t),s(null)),null),[u]),h=(0,t.useCallback)(()=>{d(),a(!1)},[d]);return{loading:i,data:o,error:c,beginRequest:f,setSuccess:p,setFailure:m,finishRequest:(0,t.useCallback)(e=>{u(e)&&(a(!1),r.current=null)},[u]),cancel:h,reset:(0,t.useCallback)(()=>{h(),s(null),l(null)},[h])}}function g(e){if(e)return e;throw Error(`useJapanAddressSearch requires options.dataSource`)}function _(e){return e?.trim()||void 0}function v(e){let t=typeof e==`string`?{addressQuery:e}:e,n=_(t.addressQuery),r=_(t.prefCode),i=_(t.prefName),a=_(t.prefKana),o=_(t.prefRoma),s=_(t.cityCode),c=_(t.cityName),l=_(t.cityKana),u=_(t.cityRoma),d=_(t.townName),f=_(t.townKana),p=_(t.townRoma);return n===void 0&&r===void 0&&i===void 0&&a===void 0&&o===void 0&&s===void 0&&c===void 0&&l===void 0&&u===void 0&&d===void 0&&f===void 0&&p===void 0?null:{...n===void 0?{}:{addressQuery:n},...r===void 0?{}:{prefCode:r},...i===void 0?{}:{prefName:i},...a===void 0?{}:{prefKana:a},...o===void 0?{}:{prefRoma:o},...s===void 0?{}:{cityCode:s},...c===void 0?{}:{cityName:c},...l===void 0?{}:{cityKana:l},...u===void 0?{}:{cityRoma:u},...d===void 0?{}:{townName:d},...f===void 0?{}:{townKana:f},...p===void 0?{}:{townRoma:p},pageNumber:t.pageNumber??0,rowsPerPage:t.rowsPerPage??100,...t.includeCityDetails===void 0?{}:{includeCityDetails:t.includeCityDetails},...t.includePrefectureDetails===void 0?{}:{includePrefectureDetails:t.includePrefectureDetails}}}function y(e){return e.aborted?Promise.resolve(null):new Promise(t=>{let n=()=>{e.removeEventListener(`abort`,n),t(null)};e.addEventListener(`abort`,n,{once:!0})})}function b(e){let n=(0,t.useMemo)(()=>g(e.dataSource),[e.dataSource]),r=e.debounceMs??0,i=(0,t.useRef)(null),a=(0,t.useRef)(null),{loading:o,data:s,error:c,beginRequest:l,setSuccess:d,setFailure:f,finishRequest:p,cancel:_,reset:b}=h(),x=(0,t.useCallback)(e=>{i.current!==null&&(globalThis.clearTimeout(i.current),i.current=null),a.current?.(e),a.current=null},[]);(0,t.useEffect)(()=>()=>{x(null)},[x]);let S=(0,t.useCallback)(()=>{x(null),b()},[x,b]),C=(0,t.useCallback)(()=>{x(null),_()},[x,_]),w=(0,t.useCallback)(async(e,t,r)=>{try{let i={signal:t},a=n.searchAddress(r,i),o=await Promise.race([a,y(t)]);return t.aborted||o===null?null:(d(e,o),o)}catch(n){return t.aborted?null:f(e,m(n))}finally{p(e)}},[n,p,f,d]);return{loading:o,data:s,error:c,cancel:C,reset:S,search:(0,t.useCallback)(e=>{let t=v(e),{requestId:n,signal:o}=l();if(x(null),t===null){let e=f(n,u(`invalid_query`,`Address query is required`));return p(n),Promise.resolve(e)}return r<=0?new Promise(e=>{a.current=e,w(n,o,t).then(t=>{e(t),a.current===e&&(a.current=null)})}):new Promise(e=>{a.current=e,i.current=globalThis.setTimeout(()=>{i.current=null;let e=a.current;a.current=null,w(n,o,t).then(t=>{e?.(t)})},r)})},[l,x,r,w])}}function x(e){if(e)return e;throw Error(`useJapanPostalCode requires options.dataSource`)}function S(e){let n=(0,t.useMemo)(()=>x(e.dataSource),[e.dataSource]),{loading:r,data:i,error:a,beginRequest:o,setSuccess:c,setFailure:l,finishRequest:d,cancel:f,reset:p}=h();return{loading:r,data:i,error:a,cancel:f,reset:p,search:(0,t.useCallback)(async e=>{let{requestId:t,signal:r}=o();try{let i=typeof e==`string`?{postalCode:e}:e,a=s(i.postalCode);if(!/^\d{3,7}$/.test(a))throw u(`invalid_postal_code`,`Postal code must contain between 3 and 7 digits`);let o={signal:r},l={postalCode:a,pageNumber:i.pageNumber??0,rowsPerPage:i.rowsPerPage??100,...i.includeParenthesesTown===void 0?{}:{includeParenthesesTown:i.includeParenthesesTown}},d=await n.lookupPostalCode(l,o);return r.aborted?null:(c(t,d),d)}catch(e){return r.aborted?null:l(t,m(e))}finally{d(t)}},[o,n,d,l,c])}}function C(e){let n=(0,t.useMemo)(()=>{if(e.dataSource)return e.dataSource;throw Error(`useJapanAddress requires options.dataSource`)},[e.dataSource]),r=S({dataSource:n}),i=b({dataSource:n,debounceMs:e.debounceMs}),a=r.reset,o=r.search,s=i.reset,c=i.search,[l,u]=(0,t.useState)(null),d=(0,t.useCallback)(async e=>(s(),u(`postalCode`),o(e)),[s,o]),f=(0,t.useCallback)(async e=>(a(),u(`addressQuery`),c(e)),[a,c]),p=(0,t.useCallback)(()=>{a(),s(),u(null)},[s,a]),m=l===`postalCode`?r.data:l===`addressQuery`?i.data:null,h=l===`postalCode`?r.error:l===`addressQuery`?i.error:null;return{loading:r.loading||i.loading,data:m,error:h,reset:p,searchByPostalCode:d,searchByAddressQuery:f}}e.AddressSearchInput=o,e.PostalCodeInput=l,e.createJapanAddressError=u,e.formatJapanPostalCode=c,e.isValidJapanPostalCode=p,e.normalizeJapanPostAddressRecord=f,e.normalizeJapanPostalCode=s,e.useJapanAddress=C,e.useJapanAddressSearch=b,e.useJapanPostalCode=S});

package/dist/{components → src/components}/AddressSearchInput.d.ts

@@ -2,6 +2,7 @@ import { AddressSearchInputProps } from '../core/types';
 /**
  * 스타일 의존성이 없는 최소한의 주소 키워드 검색 입력 컴포넌트.
  * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ * 검색 시 trim 처리를 내부에서 수행해 공백만 다른 입력이 별도 쿼리로 번지지 않게 한다.
  */
 export declare function AddressSearchInput({ defaultValue, value, disabled, label, buttonLabel, inputProps, buttonProps, onChange, onSearch, }: AddressSearchInputProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=AddressSearchInput.d.ts.map

package/dist/src/components/AddressSearchInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddressSearchInput.d.ts","sourceRoot":"","sources":["../../../src/components/AddressSearchInput.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,YAAiB,EACjB,KAAK,EACL,QAAQ,EACR,KAAyB,EACzB,WAAsB,EACtB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,EAAE,uBAAuB,2CA4CzB"}

package/dist/{components → src/components}/PostalCodeInput.d.ts

@@ -2,6 +2,7 @@ import { PostalCodeInputProps } from '../core/types';
 /**
  * 스타일 의존성이 없는 최소한의 우편번호 입력 컴포넌트.
  * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ * 제출 시에는 표시 형식이 아니라 정규화된 숫자 문자열을 콜백에 넘기는 것이 핵심 계약이다.
  */
 export declare function PostalCodeInput({ defaultValue, value, disabled, label, buttonLabel, inputProps, buttonProps, onChange, onSearch, }: PostalCodeInputProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=PostalCodeInput.d.ts.map

package/dist/src/components/PostalCodeInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostalCodeInput.d.ts","sourceRoot":"","sources":["../../../src/components/PostalCodeInput.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAC9B,YAAiB,EACjB,KAAK,EACL,QAAQ,EACR,KAAqB,EACrB,WAAsB,EACtB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,EAAE,oBAAoB,2CA8CtB"}

package/dist/src/core/errors.d.ts

@@ -0,0 +1,11 @@
+import { JapanAddressError, JapanAddressErrorCode } from './types';
+/**
+ * 라이브러리 전반에서 공통으로 쓰는 오류 객체 생성기다.
+ * 브라우저 fetch 오류, validation 오류, data source 오류를 모두 같은 표면으로 맞춰
+ * 소비자가 code/status만으로 분기할 수 있게 한다.
+ */
+export declare function createJapanAddressError(code: JapanAddressErrorCode, message: string, options?: {
+    cause?: unknown;
+    status?: number;
+}): JapanAddressError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,iBAAiB,CAQnB"}

package/dist/src/core/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../../src/core/formatters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW3D"}

package/dist/{core → src/core}/normalizers.d.ts

@@ -1,7 +1,7 @@
 import { JapanAddress, NormalizedJapanAddressRecord } from './types';
 /**
  * 정규화된 내부 주소 레코드를 라이브러리 공개 JapanAddress 형태로 변환한다.
- * address는 도도부현·시구정촌·동·상세주소를 순서대로 이어붙인 문자열이다.
+ * address는 표시용 convenience 필드이므로, 구조화된 필드와 같은 순서를 유지해 예측 가능성을 보장한다.
  */
 export declare function normalizeJapanPostAddressRecord(record: NormalizedJapanAddressRecord): JapanAddress;
 //# sourceMappingURL=normalizers.d.ts.map

package/dist/src/core/normalizers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizers.d.ts","sourceRoot":"","sources":["../../../src/core/normalizers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAe1E;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,4BAA4B,GACnC,YAAY,CAoBd"}

package/dist/src/core/types.d.ts

@@ -0,0 +1,261 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+/**
+ * `japanpost-react`의 공개 계약과 내부 정규화 계약을 한 곳에 모아 둔 타입 모음이다.
+ * 훅, 입력 컴포넌트, data source, minimal-api 연동 예제가 모두 이 정의를 기준으로 맞물리므로
+ * 필드 의미를 바꿀 때는 런타임 동작뿐 아니라 외부 사용자의 기대 계약도 함께 고려해야 한다.
+ */
+/**
+ * 일본우정 API에서 반환되는 원본 주소 레코드 형태.
+ * 공개 API 표면에는 직접 노출하지 않고 내부에서만 사용한다.
+ */
+export type JapanPostApiAddressRecord = {
+    zip_code?: string | number | null;
+    pref_code?: string | number | null;
+    pref_name?: string | null;
+    pref_kana?: string | null;
+    city_name?: string | null;
+    city_kana?: string | null;
+    town_name?: string | null;
+    town_kana?: string | null;
+    block_name?: string | null;
+    other_name?: string | null;
+    address?: string | null;
+};
+/**
+ * 우편번호로 주소를 검색할 때(searchcode) API 응답 형태.
+ */
+export type JapanPostSearchCodeResponse = {
+    addresses?: JapanPostApiAddressRecord[] | null;
+    message?: string | null;
+    status?: number;
+};
+/**
+ * 주소 키워드로 검색할 때(addresszip) API 응답 형태.
+ */
+export type JapanPostAddressZipResponse = {
+    addresses?: JapanPostApiAddressRecord[] | null;
+    message?: string | null;
+    status?: number;
+};
+export type JapanPostApiResponse = JapanPostSearchCodeResponse | JapanPostAddressZipResponse;
+/**
+ * minimal-api가 그대로 받는 공개 searchcode 요청 타입이다.
+ * pageNumber/rowsPerPage를 노출하는 이유는 라이브러리와 API 예제가 같은 pager 의미 체계를 공유하기 위해서다.
+ */
+export type JapanPostSearchcodeRequest = {
+    postalCode: string;
+    pageNumber: number;
+    rowsPerPage: number;
+    includeParenthesesTown?: boolean | null;
+};
+/**
+ * useJapanPostalCode의 공개 검색 입력 타입.
+ * 문자열 입력은 기존 호환성을 유지하고, 객체 입력은 pager 옵션을 함께 전달할 수 있게 한다.
+ */
+export type JapanPostalCodeSearchInput = string | {
+    postalCode: string;
+    pageNumber?: number;
+    rowsPerPage?: number;
+    includeParenthesesTown?: boolean | null;
+};
+/**
+ * useJapanAddressSearch의 공개 검색 입력 타입.
+ * 문자열 입력은 키워드 검색 호환성을 유지하고, 객체 입력은 자유 검색과 구조화 검색 필드를 함께 전달할 수 있게 한다.
+ */
+export type JapanAddressSearchInput = string | (Omit<JapanPostAddresszipRequest, "pageNumber" | "rowsPerPage"> & {
+    pageNumber?: number;
+    rowsPerPage?: number;
+});
+/**
+ * minimal-api가 그대로 받는 공개 addresszip 요청 타입이다.
+ * 자유 검색(addressQuery)뿐 아니라 구조화 검색 필드도 함께 열어 두어
+ * 상위 UI가 필요한 만큼만 업스트림 검색 축을 선택적으로 노출할 수 있게 한다.
+ */
+export type JapanPostAddresszipRequest = {
+    addressQuery?: string | null;
+    prefCode?: string | null;
+    prefName?: string | null;
+    prefKana?: string | null;
+    prefRoma?: string | null;
+    cityCode?: string | null;
+    cityName?: string | null;
+    cityKana?: string | null;
+    cityRoma?: string | null;
+    townName?: string | null;
+    townKana?: string | null;
+    townRoma?: string | null;
+    pageNumber: number;
+    rowsPerPage: number;
+    includeCityDetails?: boolean | null;
+    includePrefectureDetails?: boolean | null;
+};
+/**
+ * API 응답을 정규화한 후의 중간 주소 레코드 형태.
+ * 내부 data source 처리 후 공개 JapanAddress 타입으로 변환되기 전에 사용된다.
+ */
+export type NormalizedJapanAddressRecord = {
+    postalCode: string;
+    prefecture: string;
+    prefectureKana?: string;
+    city: string;
+    cityKana?: string;
+    town: string;
+    townKana?: string;
+    detail?: string;
+};
+/**
+ * 라이브러리 공개 주소 타입. 훅과 클라이언트가 외부로 반환하는 최종 형태.
+ * `address`는 표시 편의를 위한 결합 문자열이고, 나머지 필드는 후처리/재조합이 가능한 구조화 값이다.
+ */
+export type JapanAddress = {
+    postalCode: string;
+    prefecture: string;
+    prefectureKana?: string;
+    city: string;
+    cityKana?: string;
+    town: string;
+    townKana?: string;
+    address: string;
+    provider: "japan-post";
+};
+/**
+ * minimal-api와 라이브러리가 공통으로 사용하는 pager 응답 계약이다.
+ * 페이지 기반 UI가 아니더라도 total/page 정보를 유지해 "결과 없음"과 "일부만 조회됨"을 구분할 수 있다.
+ */
+export type Page<T> = {
+    elements: T[];
+    totalElements: number;
+    pageNumber: number;
+    rowsPerPage: number;
+};
+/**
+ * 우편번호 조회 결과.
+ * 단일 주소만 기대하는 소비자도 있을 수 있지만, 업스트림 계약이 목록 + 페이징이므로 그대로 보존한다.
+ */
+export type JapanPostalCodeLookupResult = Page<JapanAddress>;
+/**
+ * 키워드 주소 검색 결과.
+ * postal code 조회와 동일한 pager 형태를 사용해 두 검색 모드를 같은 UI로 렌더링할 수 있게 한다.
+ */
+export type JapanAddressSearchResult = Page<JapanAddress>;
+/**
+ * 라이브러리 전용 오류 코드 목록.
+ * 소비자는 message 문자열보다 code를 기준으로 UX를 분기하는 것이 안전하다.
+ */
+export type JapanAddressErrorCode = "invalid_postal_code" | "invalid_query" | "network_error" | "timeout" | "not_found" | "bad_response" | "data_source_error";
+/**
+ * 라이브러리 전용 에러 타입. 훅과 data source 전반에서 일관되게 사용된다.
+ * 브라우저/서버/사용자 입력 오류를 모두 같은 형태로 감싸 public contract를 단순화한다.
+ */
+export type JapanAddressError = Error & {
+    name: "JapanAddressError";
+    code: JapanAddressErrorCode;
+    cause?: unknown;
+    status?: number;
+};
+/**
+ * data source 요청에 전달할 선택 옵션.
+ * 현재는 AbortSignal만 쓰지만, 추후 timeout/metadata가 필요해져도 호출부 시그니처를 크게 흔들지 않기 위한 확장 지점이다.
+ */
+export type JapanAddressRequestOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * 주소 데이터를 제공하는 data source 인터페이스.
+ * 커스텀 구현체로 교체할 수 있도록 추상화되어 있다.
+ * 즉, 훅은 fetch 구현을 모르고 pager 계약과 에러 계약만 신뢰한다.
+ */
+export type JapanAddressDataSource = {
+    lookupPostalCode: (request: JapanPostSearchcodeRequest, options?: JapanAddressRequestOptions) => Promise<Page<JapanAddress>>;
+    searchAddress: (request: JapanPostAddresszipRequest, options?: JapanAddressRequestOptions) => Promise<Page<JapanAddress>>;
+};
+/**
+ * useJapanPostalCode 훅 옵션.
+ * data source 주입 방식으로 브라우저 직접 호출, BFF, mock을 모두 같은 훅으로 다룬다.
+ */
+export type UseJapanPostalCodeOptions = {
+    dataSource: JapanAddressDataSource;
+};
+/**
+ * useJapanAddressSearch 훅 옵션.
+ * debounce는 UI 입력 빈도를 제어하기 위한 것이며 data source 계약을 바꾸지 않는다.
+ */
+export type UseJapanAddressSearchOptions = {
+    dataSource: JapanAddressDataSource;
+    debounceMs?: number;
+};
+/**
+ * useJapanAddress 훅 옵션.
+ * 통합 훅도 내부적으로는 두 검색 훅을 조합하므로 필요한 옵션만 얇게 위임한다.
+ */
+export type UseJapanAddressOptions = {
+    dataSource: JapanAddressDataSource;
+    debounceMs?: number;
+};
+/**
+ * 비동기 데이터 로딩 상태를 표현하는 제네릭 타입.
+ * 모든 훅이 같은 상태 모양을 공유하면 소비자 컴포넌트가 검색 종류와 무관하게 공통 렌더링 로직을 가질 수 있다.
+ */
+export type UseAsyncState<T> = {
+    loading: boolean;
+    data: T | null;
+    error: JapanAddressError | null;
+};
+/**
+ * useJapanPostalCode 훅의 반환 타입.
+ * search는 실패나 취소 시 null을 반환해 UI가 try/catch 없이도 분기할 수 있게 한다.
+ */
+export type UseJapanPostalCodeResult = UseAsyncState<JapanPostalCodeLookupResult> & {
+    cancel: () => void;
+    reset: () => void;
+    search: (input: JapanPostalCodeSearchInput) => Promise<JapanPostalCodeLookupResult | null>;
+};
+/**
+ * useJapanAddressSearch 훅의 반환 타입.
+ * debounce 취소와 오류 모두 Promise 결과 관점에서는 null로 귀결될 수 있으므로 호출부는 state와 함께 해석해야 한다.
+ */
+export type UseJapanAddressSearchResult = UseAsyncState<JapanAddressSearchResult> & {
+    cancel: () => void;
+    reset: () => void;
+    search: (input: JapanAddressSearchInput) => Promise<JapanAddressSearchResult | null>;
+};
+/**
+ * useJapanAddress 훅의 반환 타입.
+ * data/error는 "현재 활성 검색 모드" 기준 값이며, 두 내부 훅의 상태 전체를 그대로 노출하지는 않는다.
+ */
+export type UseJapanAddressResult = UseAsyncState<Page<JapanAddress>> & {
+    reset: () => void;
+    searchByPostalCode: (input: JapanPostalCodeSearchInput) => Promise<JapanPostalCodeLookupResult | null>;
+    searchByAddressQuery: (input: JapanAddressSearchInput) => Promise<JapanAddressSearchResult | null>;
+};
+/**
+ * 검색 입력 컴포넌트들이 공유하는 공통 props.
+ * 제어/비제어 모드를 모두 지원해 폼 라이브러리와 단순 데모 예제를 같은 컴포넌트로 소화한다.
+ */
+type BaseTextSearchInputProps = {
+    defaultValue?: string;
+    value?: string;
+    disabled?: boolean;
+    label?: ReactNode;
+    buttonLabel?: ReactNode;
+    inputProps?: Omit<ComponentPropsWithoutRef<"input">, "defaultValue" | "disabled" | "onChange" | "value">;
+    buttonProps?: Omit<ComponentPropsWithoutRef<"button">, "children" | "disabled" | "onClick" | "type">;
+};
+/**
+ * PostalCodeInput 컴포넌트 props.
+ * onSearch는 표시 문자열이 아니라 정규화된 우편번호를 받는다는 점이 핵심 계약이다.
+ */
+export type PostalCodeInputProps = BaseTextSearchInputProps & {
+    onChange?: (postalCode: string) => void;
+    onSearch: (postalCode: string) => void;
+};
+/**
+ * AddressSearchInput 컴포넌트 props.
+ * onSearch에는 trim 처리된 검색어가 전달되어 공백만 다른 입력이 별도 쿼리로 취급되지 않게 한다.
+ */
+export type AddressSearchInputProps = BaseTextSearchInputProps & {
+    onChange?: (query: string) => void;
+    onSearch: (query: string) => void;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/src/core/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/core/validators.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG7D"}