@pro6pp/infer-core 0.0.2-beta.4 → 0.0.2-beta.6

package/README.md

@@ -22,17 +22,28 @@ const core = new InferCore({
   authKey: 'YOUR_AUTH_KEY',
   country: 'NL',
   onStateChange: (state) => {
-    console.log('Current Suggestions:', state.suggestions);
-    console.log('Is Loading:', state.isLoading);
+    // suggestions, isLoading, isValid, selectedSuggestionIndex, etc.
+    console.log('Current State:', state);
   },
   onSelect: (result) => {
     console.log('User selected:', result);
   },
 });
 
-// feed it input events, e.g. via an <input>
-core.handleInput('Amsterdam');
+const input = document.querySelector('#my-input');
 
-// handle selections when user clicks a suggestion in your dropdown
-core.selectItem(suggestionObject);
+// pass input events to the core
+input.addEventListener('input', (e) => {
+  core.handleInput(e.target.value);
+});
+
+// pass keyboard events
+input.addEventListener('keydown', (e) => {
+  core.handleKeyDown(e);
+});
+
+// handle clicks
+function onSuggestionClick(item) {
+  core.selectItem(item);
+}
 ```

package/dist/index.cjs

@@ -1 +1,99 @@
-"use strict";var o=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var S=Object.prototype.hasOwnProperty;var m=(n,t,e)=>t in n?o(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e;var I=(n,t)=>{for(var e in t)o(n,e,{get:t[e],enumerable:!0})},y=(n,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of f(t))!S.call(n,r)&&r!==e&&o(n,r,{get:()=>t[r],enumerable:!(s=p(t,r))||s.enumerable});return n};var v=n=>y(o({},"__esModule",{value:!0}),n);var a=(n,t,e)=>m(n,typeof t!="symbol"?t+"":t,e);var x={};I(x,{INITIAL_STATE:()=>h,InferCore:()=>c});module.exports=v(x);var l={API_URL:"https://api.pro6pp.nl/v2",LIMIT:1e3,DEBOUNCE_MS:300},g={DIGITS_1_3:/^[0-9]{1,3}$/},h={query:"",stage:null,cities:[],streets:[],suggestions:[],isValid:!1,isError:!1,isLoading:!1,selectedSuggestionIndex:-1},c=class{constructor(t){a(this,"country");a(this,"authKey");a(this,"apiUrl");a(this,"limit");a(this,"fetcher");a(this,"onStateChange");a(this,"onSelect");a(this,"state");a(this,"abortController",null);a(this,"debouncedFetch");this.country=t.country,this.authKey=t.authKey,this.apiUrl=t.apiUrl||l.API_URL,this.limit=t.limit||l.LIMIT,this.fetcher=t.fetcher||((e,s)=>fetch(e,s)),this.onStateChange=t.onStateChange||(()=>{}),this.onSelect=t.onSelect||(()=>{}),this.state={...h},this.debouncedFetch=this.debounce(e=>this.executeFetch(e),l.DEBOUNCE_MS)}handleInput(t){this.updateState({query:t,isValid:!1,isLoading:!!t.trim(),selectedSuggestionIndex:-1}),this.state.stage==="final"&&this.onSelect(null),this.debouncedFetch(t)}handleKeyDown(t){let e=t.target;if(!e)return;let s=this.state.cities.length+this.state.streets.length+this.state.suggestions.length;if(s>0){if(t.key==="ArrowDown"){t.preventDefault();let i=this.state.selectedSuggestionIndex+1;i>=s&&(i=0),this.updateState({selectedSuggestionIndex:i});return}if(t.key==="ArrowUp"){t.preventDefault();let i=this.state.selectedSuggestionIndex-1;i<0&&(i=s-1),this.updateState({selectedSuggestionIndex:i});return}if(t.key==="Enter"&&this.state.selectedSuggestionIndex>=0){t.preventDefault();let u=[...this.state.cities,...this.state.streets,...this.state.suggestions][this.state.selectedSuggestionIndex];u&&(this.selectItem(u),this.updateState({selectedSuggestionIndex:-1}));return}}let r=e.value;if(t.key===" "&&this.shouldAutoInsertComma(r)){t.preventDefault();let i=`${r.trim()}, `;this.updateQueryAndFetch(i)}}selectItem(t){let e=typeof t=="string"?t:t.label,s=typeof t!="string"?t.value:void 0,r=typeof t!="string"?t.subtitle:null;if(this.state.stage==="final"){this.finishSelection(e,s);return}this.processSelection(e,r)}shouldAutoInsertComma(t){if(!t.includes(",")&&g.DIGITS_1_3.test(t.trim()))return!0;if(this.state.stage==="house_number"){let s=this.getCurrentFragment(t);return g.DIGITS_1_3.test(s)}return!1}finishSelection(t,e){this.updateState({query:t,suggestions:[],cities:[],streets:[],isValid:!0}),this.onSelect(e||t)}processSelection(t,e){let{stage:s,query:r}=this.state,i=r;if(e&&(s==="city"||s==="street"||s==="mixed")){if(s==="city")i=`${e}, ${t}, `;else{let d=this.getQueryPrefix(r);i=d?`${d} ${t}, ${e}, `:`${t}, ${e}, `}this.updateQueryAndFetch(i);return}if(s==="direct"||s==="addition"){this.finishSelection(t);return}!r.includes(",")&&(s==="city"||s==="street"||s==="house_number_first")?i=`${t}, `:(i=this.replaceLastSegment(r,t),s!=="house_number"&&(i+=", ")),this.updateQueryAndFetch(i)}executeFetch(t){let e=(t||"").toString();if(!e.trim()){this.abortController?.abort(),this.resetState();return}this.updateState({isError:!1}),this.abortController&&this.abortController.abort(),this.abortController=new AbortController;let s=new URL(`${this.apiUrl}/infer/${this.country.toLowerCase()}`),r={authKey:this.authKey,query:e,limit:this.limit.toString()};s.search=new URLSearchParams(r).toString(),this.fetcher(s.toString(),{signal:this.abortController.signal}).then(i=>{if(!i.ok)throw new Error("Network error");return i.json()}).then(i=>this.mapResponseToState(i)).catch(i=>{i.name!=="AbortError"&&this.updateState({isError:!0,isLoading:!1})})}mapResponseToState(t){let e={stage:t.stage,isLoading:!1};t.stage==="mixed"?(e.cities=t.cities||[],e.streets=t.streets||[],e.suggestions=[]):(e.suggestions=t.suggestions||[],e.cities=[],e.streets=[]),e.isValid=t.stage==="final",this.updateState(e)}updateQueryAndFetch(t){this.updateState({query:t,suggestions:[],cities:[],streets:[]}),this.handleInput(t)}replaceLastSegment(t,e){let s=t.lastIndexOf(",");return s===-1?e:`${t.slice(0,s+1)} ${e}`.trim()}getQueryPrefix(t){let e=t.lastIndexOf(",");return e===-1?"":t.slice(0,e+1).trimEnd()}getCurrentFragment(t){return(t.split(",").slice(-1)[0]??"").trim()}resetState(){this.updateState({...h,query:this.state.query})}updateState(t){this.state={...this.state,...t},this.onStateChange(this.state)}debounce(t,e){let s;return(...r)=>{s&&clearTimeout(s),s=setTimeout(()=>t.apply(this,r),e)}}};0&&(module.exports={INITIAL_STATE,InferCore});
+"use strict";var c=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var I=Object.prototype.hasOwnProperty;var C=(n,e,t)=>e in n?c(n,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):n[e]=t;var T=(n,e)=>{for(var t in e)c(n,t,{get:e[t],enumerable:!0})},w=(n,e,t,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of v(e))!I.call(n,i)&&i!==t&&c(n,i,{get:()=>e[i],enumerable:!(s=y(e,i))||s.enumerable});return n};var _=n=>w(c({},"__esModule",{value:!0}),n);var o=(n,e,t)=>C(n,typeof e!="symbol"?e+"":e,t);var F={};T(F,{DEFAULT_STYLES:()=>b,INITIAL_STATE:()=>h,InferCore:()=>g});module.exports=_(F);var d={API_URL:"https://api.pro6pp.nl/v2",LIMIT:1e3,DEBOUNCE_MS:150,MIN_DEBOUNCE_MS:50},m={DIGITS_1_3:/^[0-9]{1,3}$/},h={query:"",stage:null,cities:[],streets:[],suggestions:[],isValid:!1,isError:!1,isLoading:!1,selectedSuggestionIndex:-1},g=class{constructor(e){o(this,"country");o(this,"authKey");o(this,"apiUrl");o(this,"limit");o(this,"fetcher");o(this,"onStateChange");o(this,"onSelect");o(this,"state");o(this,"abortController",null);o(this,"debouncedFetch");o(this,"isSelecting",!1);this.country=e.country,this.authKey=e.authKey,this.apiUrl=e.apiUrl||d.API_URL,this.limit=e.limit||d.LIMIT,this.fetcher=e.fetcher||((i,r)=>fetch(i,r)),this.onStateChange=e.onStateChange||(()=>{}),this.onSelect=e.onSelect||(()=>{}),this.state={...h};let t=e.debounceMs!==void 0?e.debounceMs:d.DEBOUNCE_MS,s=Math.max(t,d.MIN_DEBOUNCE_MS);this.debouncedFetch=this.debounce(i=>this.executeFetch(i),s)}handleInput(e){if(this.isSelecting){this.isSelecting=!1;return}let t=this.state.stage==="final"&&e!==this.state.query;this.updateState({query:e,isValid:!1,isLoading:!!e.trim(),selectedSuggestionIndex:-1}),t&&this.onSelect(null),this.debouncedFetch(e)}handleKeyDown(e){let t=e.target;if(!t)return;let s=this.state.cities.length+this.state.streets.length+this.state.suggestions.length;if(s>0){if(e.key==="ArrowDown"){e.preventDefault();let r=this.state.selectedSuggestionIndex+1;r>=s&&(r=0),this.updateState({selectedSuggestionIndex:r});return}if(e.key==="ArrowUp"){e.preventDefault();let r=this.state.selectedSuggestionIndex-1;r<0&&(r=s-1),this.updateState({selectedSuggestionIndex:r});return}if(e.key==="Enter"&&this.state.selectedSuggestionIndex>=0){e.preventDefault();let a=[...this.state.cities,...this.state.streets,...this.state.suggestions][this.state.selectedSuggestionIndex];a&&(this.selectItem(a),this.updateState({selectedSuggestionIndex:-1}));return}}let i=t.value;if(e.key===" "&&this.shouldAutoInsertComma(i)){e.preventDefault();let r=`${i.trim()}, `;this.updateQueryAndFetch(r)}}selectItem(e){this.debouncedFetch.cancel(),this.abortController&&this.abortController.abort();let t=typeof e=="string"?e:e.label,s=t;typeof e!="string"&&typeof e.value=="string"&&(s=e.value);let i=typeof e!="string"&&typeof e.value=="object"?e.value:void 0,r=!!i&&Object.keys(i).length>0;if(this.isSelecting=!0,this.state.stage==="final"||r){let p=t;if(i&&Object.keys(i).length>0){let{street:l,street_number:u,house_number:x,city:f}=i,S=u||x;l&&S&&f&&(p=`${l} ${S}, ${f}`)}this.finishSelection(p,i);return}let a=typeof e!="string"?e.subtitle:null;this.processSelection(s,a)}shouldAutoInsertComma(e){if(!e.includes(",")&&m.DIGITS_1_3.test(e.trim()))return!0;if(this.state.stage==="house_number"){let s=this.getCurrentFragment(e);return m.DIGITS_1_3.test(s)}return!1}finishSelection(e,t){this.updateState({query:e,suggestions:[],cities:[],streets:[],isValid:!0,stage:"final"}),this.onSelect(t||e),setTimeout(()=>{this.isSelecting=!1},0)}processSelection(e,t){let{stage:s,query:i}=this.state,r=i;if(t&&(s==="city"||s==="street"||s==="mixed")){if(s==="city")r=`${t}, ${e}, `;else{let u=this.getQueryPrefix(i);r=u?`${u} ${e}, ${t}, `:`${e}, ${t}, `}this.updateQueryAndFetch(r);return}if(s==="direct"||s==="addition"){this.finishSelection(e);return}!i.includes(",")&&(s==="city"||s==="street"||s==="house_number_first")?r=`${e}, `:(r=this.replaceLastSegment(i,e),s!=="house_number"&&(r+=", ")),this.updateQueryAndFetch(r)}executeFetch(e){let t=(e||"").toString();if(!t.trim()){this.abortController?.abort(),this.resetState();return}this.updateState({isError:!1}),this.abortController&&this.abortController.abort(),this.abortController=new AbortController;let s=new URL(`${this.apiUrl}/infer/${this.country.toLowerCase()}`),i={authKey:this.authKey,query:t,limit:this.limit.toString()};s.search=new URLSearchParams(i).toString(),this.fetcher(s.toString(),{signal:this.abortController.signal}).then(r=>{if(!r.ok)throw new Error("Network error");return r.json()}).then(r=>this.mapResponseToState(r)).catch(r=>{r.name!=="AbortError"&&this.updateState({isError:!0,isLoading:!1})})}mapResponseToState(e){let t={stage:e.stage,isLoading:!1},s=!1,i=null,r=e.suggestions||[],a=[],p=new Set;for(let l of r){let u=`${l.label}|${l.subtitle||""}|${JSON.stringify(l.value||{})}`;p.has(u)||(p.add(u),a.push(l))}if(e.stage==="mixed"?(t.cities=e.cities||[],t.streets=e.streets||[],t.suggestions=[]):(t.suggestions=a,t.cities=[],t.streets=[],e.stage==="final"&&a.length===1&&(s=!0,i=a[0])),t.isValid=e.stage==="final",s&&i){t.query=i.label,t.suggestions=[],t.cities=[],t.streets=[],t.isValid=!0,this.updateState(t);let l=typeof i.value=="object"?i.value:i.label;this.onSelect(l)}else this.updateState(t)}updateQueryAndFetch(e){this.updateState({query:e,suggestions:[],cities:[],streets:[]}),this.updateState({isLoading:!0,isValid:!1}),this.debouncedFetch(e),setTimeout(()=>{this.isSelecting=!1},0)}replaceLastSegment(e,t){let s=e.lastIndexOf(",");return s===-1?t:`${e.slice(0,s+1)} ${t}`.trim()}getQueryPrefix(e){let t=e.lastIndexOf(",");return t===-1?"":e.slice(0,t+1).trimEnd()}getCurrentFragment(e){return(e.split(",").slice(-1)[0]??"").trim()}resetState(){this.updateState({...h,query:this.state.query})}updateState(e){this.state={...this.state,...e},this.onStateChange(this.state)}debounce(e,t){let s,i=(...r)=>{s&&clearTimeout(s),s=setTimeout(()=>e.apply(this,r),t)};return i.cancel=()=>{s&&(clearTimeout(s),s=void 0)},i}};var b=`
+  .pro6pp-wrapper {
+    position: relative;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    box-sizing: border-box;
+    width: 100%;
+  }
+  .pro6pp-wrapper * {
+    box-sizing: border-box;
+  }
+  .pro6pp-input {
+    width: 100%;
+    padding: 10px 12px;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    font-size: 16px;
+    line-height: 1.5;
+    transition: border-color 0.2s, box-shadow 0.2s;
+  }
+  .pro6pp-input:focus {
+    outline: none;
+    border-color: #3b82f6;
+    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+  }
+  .pro6pp-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: 9999;
+    margin-top: 4px;
+    background: white;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+    max-height: 300px;
+    overflow-y: auto;
+    list-style: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+  }
+  .pro6pp-item {
+    padding: 10px 16px;
+    cursor: pointer;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    color: #000000;
+    font-size: 14px;
+    line-height: 1.2;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+  .pro6pp-item:hover, .pro6pp-item--active {
+    background-color: #f5f5f5;
+  }
+  .pro6pp-item__label {
+    font-weight: 500;
+    flex-shrink: 0;
+  }
+  .pro6pp-item__subtitle {
+    font-size: 14px;
+    color: #404040;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    flex-shrink: 1;
+  }
+  .pro6pp-item__chevron {
+    margin-left: auto;
+    display: flex;
+    align-items: center;
+    color: #a3a3a3;
+    padding-left: 8px;
+  }
+  .pro6pp-no-results {
+    padding: 12px;
+    color: #555555;
+    font-size: 14px;
+    text-align: center;
+    user-select: none;
+    pointer-events: none;
+  }
+  .pro6pp-loader {
+    position: absolute;
+    right: 12px;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 16px;
+    height: 16px;
+    border: 2px solid #e0e0e0;
+    border-top-color: #404040;
+    border-radius: 50%;
+    animation: pro6pp-spin 0.6s linear infinite;
+    pointer-events: none;
+  }
+  @keyframes pro6pp-spin {
+    to { transform: translateY(-50%) rotate(360deg); }
+  }
+`;0&&(module.exports={DEFAULT_STYLES,INITIAL_STATE,InferCore});

package/dist/index.d.cts

@@ -4,106 +4,139 @@
 type CountryCode = 'NL' | 'DE';
 /**
  * The current step in the address inference process.
+ * - `empty`: No input yet.
+ * - `mixed`: User is prompted to choose between cities and streets.
+ * - `street`: User is selecting a street.
+ * - `city`: User is selecting a city.
+ * - `postcode`: User is entering a postcode.
+ * - `house_number`: User is entering a house number.
+ * - `house_number_first`: Specialized mode where number is entered before street.
+ * - `addition`: Selecting a house number addition (e.g., 'A', 'III').
+ * - `direct`: Direct address hit (often via postcode).
+ * - `final`: A complete, valid address has been identified.
  */
 type Stage = 'empty' | 'mixed' | 'street' | 'city' | 'postcode' | 'house_number' | 'house_number_first' | 'addition' | 'direct' | 'final';
 /**
- * The standardized address object returned upon selection.
+ * The standardized address object returned upon a successful final selection.
  */
 interface AddressValue {
+    /** The name of the street. */
     street: string;
+    /** The name of the city/locality. */
     city: string;
+    /** The house number (formatted). */
     street_number?: string | number;
+    /** The house number (numeric part). */
     house_number?: string | number;
+    /** The postal code. */
     postcode?: string;
+    /** The full postal code including letters (country-specific). */
     postcode_full?: string;
+    /** The house number addition or suffix. */
     addition?: string;
     /** Allow for extra fields if API expands. */
     [key: string]: unknown;
 }
 /**
- * A single item in the dropdown list.
+ * A single item in the suggestion list.
  */
 interface InferResult {
-    /** The text to display in the UI (e.g. "Amsterdam"). */
+    /** The text to display in the UI (e.g. "Main Street"). */
     label: string;
-    /** The actual address data. Only present if this result completes an address. */
-    value?: AddressValue;
-    /** Helper text. */
+    /** The actual address data.
+     * Only present if this result completes an address or represents a specific entity.
+     */
+    value?: AddressValue | string;
+    /** Secondary information (e.g., city name when suggesting a street). */
     subtitle?: string | null;
-    /** Number of underlying results (optional). */
+    /** Number of underlying results found for this suggestion. */
     count?: number | string;
 }
 /**
- * The complete state returned by the `useInfer` hook.
+ * The complete UI state managed by InferCore.
  */
 interface InferState {
-    /** The current value of the input field. */
+    /** The current text value of the search input. */
     query: string;
-    /** The current inference stage. */
+    /** The current logical stage of the address lookup. */
     stage: Stage | null;
-    /** List of cities to display, specific to `mixed` mode. */
+    /** List of city suggestions (used in `mixed` stage). */
     cities: InferResult[];
-    /** List of streets to display, specific to `mixed` mode. */
+    /** List of street suggestions (used in `mixed` stage). */
     streets: InferResult[];
-    /** General suggestions to display. */
+    /** General list of suggestions for the current stage. */
     suggestions: InferResult[];
-    /** True if a full, valid address has been selected. */
+    /** Flag indicating if the current selection is a complete, valid address. */
     isValid: boolean;
-    /** True if the last network request failed. */
+    /** Flag indicating if the last API request failed. */
     isError: boolean;
-    /** True if a network request is currently active. */
+    /** Flag indicating if a network request is currently in progress. */
     isLoading: boolean;
     /**
-     * The index of the currently highlighted suggestion in the dropdown list.
-     * - Values `>= 0` indicate an active item (for keyboard navigation).
-     * - Value `-1` indicates no item is currently highlighted.
+     * The index of the currently highlighted suggestion.
+     * - `0` to `n`: An item is highlighted via keyboard navigation.
+     * - `-1`: No item is highlighted.
      */
     selectedSuggestionIndex: number;
 }
 /**
- * Custom fetch implementation, compatible with `window.fetch`.
- * Useful for server-side usage or testing.
+ * Custom fetch implementation, compatible with the Web Fetch API.
+ * Useful for Node.js environments or proxying requests.
  */
 type Fetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 /**
- * Configuration for Infer Core.
+ * Configuration options for the Infer engine.
  */
 interface InferConfig {
     /**
-     * Pro6PP Authorization Key.
+     * Your Pro6PP Authorization Key.
      */
     authKey: string;
     /**
-     * Country to search addresses in.
+     * The country to perform address lookups in.
      */
     country: CountryCode;
     /**
      * Base URL for the Pro6PP API.
-     * Useful for proxying requests through your own backend.
      * @default 'https://api.pro6pp.nl/v2'
      */
     apiUrl?: string;
     /**
-     * Custom fetch implementation.
-     * Useful for server-side usage or testing.
+     * Custom fetch implementation for network requests.
+     * @default window.fetch
      */
     fetcher?: Fetcher;
     /**
-     * Maximum number of results to return.
+     * Maximum number of suggestions to request from the API.
      * @default 1000
      */
     limit?: number;
     /**
-     * Callback fired when the internal state changes.
+     * The delay in milliseconds before performing the API search.
+     * Note: A lower bound of 50ms is enforced to protect API stability.
+     * @default 150
+     */
+    debounceMs?: number;
+    /**
+     * Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.
      */
     onStateChange?: (state: InferState) => void;
     /**
-     * Callback fired when a user selects a full valid address.
+     * Callback triggered when a user selects an item.
+     * If the address is complete, returns an `AddressValue` object.
+     * If the selection is partial, returns a `string`.
      */
     onSelect?: (selection: AddressValue | string | null) => void;
 }
 
+/**
+ * The initial state of the address inference engine.
+ */
 declare const INITIAL_STATE: InferState;
+/**
+ * The core logic engine for Pro6PP Infer.
+ * Manages API communication, state transitions, and keyboard interaction logic.
+ */
 declare class InferCore {
     private country;
     private authKey;
@@ -112,16 +145,43 @@ declare class InferCore {
     private fetcher;
     private onStateChange;
     private onSelect;
+    /**
+     * The current read-only state of the engine.
+     * Use `onStateChange` to react to updates.
+     */
     state: InferState;
     private abortController;
     private debouncedFetch;
+    private isSelecting;
+    /**
+     * Initializes a new instance of the Infer engine.
+     * @param config The configuration object including API keys and callbacks.
+     */
     constructor(config: InferConfig);
+    /**
+     * Processes new text input from the user.
+     * Triggers a debounced API request and updates the internal state.
+     * @param value The raw string from the input field.
+     */
     handleInput(value: string): void;
+    /**
+     * Handles keyboard events for the input field.
+     * Supports:
+     * - `ArrowUp`/`ArrowDown`: Navigate through the suggestion list.
+     * - `Enter`: Select the currently highlighted suggestion.
+     * - `Space`: Automatically inserts a comma if a numeric house number is detected.
+     * @param event The keyboard event from the input element.
+     */
     handleKeyDown(event: KeyboardEvent | {
         key: string;
         target: EventTarget | null;
         preventDefault: () => void;
     }): void;
+    /**
+     * Manually selects a suggestion or a string value.
+     * This is typically called when a user clicks a suggestion in the UI.
+     * @param item The suggestion object or string to select.
+     */
     selectItem(item: InferResult | string): void;
     private shouldAutoInsertComma;
     private finishSelection;
@@ -137,4 +197,6 @@ declare class InferCore {
     private debounce;
 }
 
-export { type AddressValue, type CountryCode, type Fetcher, INITIAL_STATE, type InferConfig, InferCore, type InferResult, type InferState, type Stage };
+declare const DEFAULT_STYLES = "\n  .pro6pp-wrapper {\n    position: relative;\n    font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif;\n    box-sizing: border-box;\n    width: 100%;\n  }\n  .pro6pp-wrapper * {\n    box-sizing: border-box;\n  }\n  .pro6pp-input {\n    width: 100%;\n    padding: 10px 12px;\n    border: 1px solid #e0e0e0;\n    border-radius: 4px;\n    font-size: 16px;\n    line-height: 1.5;\n    transition: border-color 0.2s, box-shadow 0.2s;\n  }\n  .pro6pp-input:focus {\n    outline: none;\n    border-color: #3b82f6;\n    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);\n  }\n  .pro6pp-dropdown {\n    position: absolute;\n    top: 100%;\n    left: 0;\n    right: 0;\n    z-index: 9999;\n    margin-top: 4px;\n    background: white;\n    border: 1px solid #e0e0e0;\n    border-radius: 4px;\n    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);\n    max-height: 300px;\n    overflow-y: auto;\n    list-style: none !important;\n    padding: 0 !important;\n    margin: 0 !important;\n  }\n  .pro6pp-item {\n    padding: 10px 16px;\n    cursor: pointer;\n    display: flex;\n    flex-direction: row;\n    align-items: center;\n    color: #000000;\n    font-size: 14px;\n    line-height: 1.2;\n    white-space: nowrap;\n    overflow: hidden;\n  }\n  .pro6pp-item:hover, .pro6pp-item--active {\n    background-color: #f5f5f5;\n  }\n  .pro6pp-item__label {\n    font-weight: 500;\n    flex-shrink: 0;\n  }\n  .pro6pp-item__subtitle {\n    font-size: 14px;\n    color: #404040;\n    overflow: hidden;\n    text-overflow: ellipsis;\n    flex-shrink: 1;\n  }\n  .pro6pp-item__chevron {\n    margin-left: auto;\n    display: flex;\n    align-items: center;\n    color: #a3a3a3;\n    padding-left: 8px;\n  }\n  .pro6pp-no-results {\n    padding: 12px;\n    color: #555555;\n    font-size: 14px;\n    text-align: center;\n    user-select: none;\n    pointer-events: none;\n  }\n  .pro6pp-loader {\n    position: absolute;\n    right: 12px;\n    top: 50%;\n    transform: translateY(-50%);\n    width: 16px;\n    height: 16px;\n    border: 2px solid #e0e0e0;\n    border-top-color: #404040;\n    border-radius: 50%;\n    animation: pro6pp-spin 0.6s linear infinite;\n    pointer-events: none;\n  }\n  @keyframes pro6pp-spin {\n    to { transform: translateY(-50%) rotate(360deg); }\n  }\n";
+
+export { type AddressValue, type CountryCode, DEFAULT_STYLES, type Fetcher, INITIAL_STATE, type InferConfig, InferCore, type InferResult, type InferState, type Stage };

package/dist/index.d.ts

@@ -4,106 +4,139 @@
 type CountryCode = 'NL' | 'DE';
 /**
  * The current step in the address inference process.
+ * - `empty`: No input yet.
+ * - `mixed`: User is prompted to choose between cities and streets.
+ * - `street`: User is selecting a street.
+ * - `city`: User is selecting a city.
+ * - `postcode`: User is entering a postcode.
+ * - `house_number`: User is entering a house number.
+ * - `house_number_first`: Specialized mode where number is entered before street.
+ * - `addition`: Selecting a house number addition (e.g., 'A', 'III').
+ * - `direct`: Direct address hit (often via postcode).
+ * - `final`: A complete, valid address has been identified.
  */
 type Stage = 'empty' | 'mixed' | 'street' | 'city' | 'postcode' | 'house_number' | 'house_number_first' | 'addition' | 'direct' | 'final';
 /**
- * The standardized address object returned upon selection.
+ * The standardized address object returned upon a successful final selection.
  */
 interface AddressValue {
+    /** The name of the street. */
     street: string;
+    /** The name of the city/locality. */
     city: string;
+    /** The house number (formatted). */
     street_number?: string | number;
+    /** The house number (numeric part). */
     house_number?: string | number;
+    /** The postal code. */
     postcode?: string;
+    /** The full postal code including letters (country-specific). */
     postcode_full?: string;
+    /** The house number addition or suffix. */
     addition?: string;
     /** Allow for extra fields if API expands. */
     [key: string]: unknown;
 }
 /**
- * A single item in the dropdown list.
+ * A single item in the suggestion list.
  */
 interface InferResult {
-    /** The text to display in the UI (e.g. "Amsterdam"). */
+    /** The text to display in the UI (e.g. "Main Street"). */
     label: string;
-    /** The actual address data. Only present if this result completes an address. */
-    value?: AddressValue;
-    /** Helper text. */
+    /** The actual address data.
+     * Only present if this result completes an address or represents a specific entity.
+     */
+    value?: AddressValue | string;
+    /** Secondary information (e.g., city name when suggesting a street). */
     subtitle?: string | null;
-    /** Number of underlying results (optional). */
+    /** Number of underlying results found for this suggestion. */
     count?: number | string;
 }
 /**
- * The complete state returned by the `useInfer` hook.
+ * The complete UI state managed by InferCore.
  */
 interface InferState {
-    /** The current value of the input field. */
+    /** The current text value of the search input. */
     query: string;
-    /** The current inference stage. */
+    /** The current logical stage of the address lookup. */
     stage: Stage | null;
-    /** List of cities to display, specific to `mixed` mode. */
+    /** List of city suggestions (used in `mixed` stage). */
     cities: InferResult[];
-    /** List of streets to display, specific to `mixed` mode. */
+    /** List of street suggestions (used in `mixed` stage). */
     streets: InferResult[];
-    /** General suggestions to display. */
+    /** General list of suggestions for the current stage. */
     suggestions: InferResult[];
-    /** True if a full, valid address has been selected. */
+    /** Flag indicating if the current selection is a complete, valid address. */
     isValid: boolean;
-    /** True if the last network request failed. */
+    /** Flag indicating if the last API request failed. */
     isError: boolean;
-    /** True if a network request is currently active. */
+    /** Flag indicating if a network request is currently in progress. */
     isLoading: boolean;
     /**
-     * The index of the currently highlighted suggestion in the dropdown list.
-     * - Values `>= 0` indicate an active item (for keyboard navigation).
-     * - Value `-1` indicates no item is currently highlighted.
+     * The index of the currently highlighted suggestion.
+     * - `0` to `n`: An item is highlighted via keyboard navigation.
+     * - `-1`: No item is highlighted.
      */
     selectedSuggestionIndex: number;
 }
 /**
- * Custom fetch implementation, compatible with `window.fetch`.
- * Useful for server-side usage or testing.
+ * Custom fetch implementation, compatible with the Web Fetch API.
+ * Useful for Node.js environments or proxying requests.
  */
 type Fetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 /**
- * Configuration for Infer Core.
+ * Configuration options for the Infer engine.
  */
 interface InferConfig {
     /**
-     * Pro6PP Authorization Key.
+     * Your Pro6PP Authorization Key.
      */
     authKey: string;
     /**
-     * Country to search addresses in.
+     * The country to perform address lookups in.
      */
     country: CountryCode;
     /**
      * Base URL for the Pro6PP API.
-     * Useful for proxying requests through your own backend.
      * @default 'https://api.pro6pp.nl/v2'
      */
     apiUrl?: string;
     /**
-     * Custom fetch implementation.
-     * Useful for server-side usage or testing.
+     * Custom fetch implementation for network requests.
+     * @default window.fetch
      */
     fetcher?: Fetcher;
     /**
-     * Maximum number of results to return.
+     * Maximum number of suggestions to request from the API.
      * @default 1000
      */
     limit?: number;
     /**
-     * Callback fired when the internal state changes.
+     * The delay in milliseconds before performing the API search.
+     * Note: A lower bound of 50ms is enforced to protect API stability.
+     * @default 150
+     */
+    debounceMs?: number;
+    /**
+     * Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.
      */
     onStateChange?: (state: InferState) => void;
     /**
-     * Callback fired when a user selects a full valid address.
+     * Callback triggered when a user selects an item.
+     * If the address is complete, returns an `AddressValue` object.
+     * If the selection is partial, returns a `string`.
      */
     onSelect?: (selection: AddressValue | string | null) => void;
 }
 
+/**
+ * The initial state of the address inference engine.
+ */
 declare const INITIAL_STATE: InferState;
+/**
+ * The core logic engine for Pro6PP Infer.
+ * Manages API communication, state transitions, and keyboard interaction logic.
+ */
 declare class InferCore {
     private country;
     private authKey;
@@ -112,16 +145,43 @@ declare class InferCore {
     private fetcher;
     private onStateChange;
     private onSelect;
+    /**
+     * The current read-only state of the engine.
+     * Use `onStateChange` to react to updates.
+     */
     state: InferState;
     private abortController;
     private debouncedFetch;
+    private isSelecting;
+    /**
+     * Initializes a new instance of the Infer engine.
+     * @param config The configuration object including API keys and callbacks.
+     */
     constructor(config: InferConfig);
+    /**
+     * Processes new text input from the user.
+     * Triggers a debounced API request and updates the internal state.
+     * @param value The raw string from the input field.
+     */
     handleInput(value: string): void;
+    /**
+     * Handles keyboard events for the input field.
+     * Supports:
+     * - `ArrowUp`/`ArrowDown`: Navigate through the suggestion list.
+     * - `Enter`: Select the currently highlighted suggestion.
+     * - `Space`: Automatically inserts a comma if a numeric house number is detected.
+     * @param event The keyboard event from the input element.
+     */
     handleKeyDown(event: KeyboardEvent | {
         key: string;
         target: EventTarget | null;
         preventDefault: () => void;
     }): void;
+    /**
+     * Manually selects a suggestion or a string value.
+     * This is typically called when a user clicks a suggestion in the UI.
+     * @param item The suggestion object or string to select.
+     */
     selectItem(item: InferResult | string): void;
     private shouldAutoInsertComma;
     private finishSelection;
@@ -137,4 +197,6 @@ declare class InferCore {
     private debounce;
 }
 
-export { type AddressValue, type CountryCode, type Fetcher, INITIAL_STATE, type InferConfig, InferCore, type InferResult, type InferState, type Stage };
+declare const DEFAULT_STYLES = "\n  .pro6pp-wrapper {\n    position: relative;\n    font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif;\n    box-sizing: border-box;\n    width: 100%;\n  }\n  .pro6pp-wrapper * {\n    box-sizing: border-box;\n  }\n  .pro6pp-input {\n    width: 100%;\n    padding: 10px 12px;\n    border: 1px solid #e0e0e0;\n    border-radius: 4px;\n    font-size: 16px;\n    line-height: 1.5;\n    transition: border-color 0.2s, box-shadow 0.2s;\n  }\n  .pro6pp-input:focus {\n    outline: none;\n    border-color: #3b82f6;\n    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);\n  }\n  .pro6pp-dropdown {\n    position: absolute;\n    top: 100%;\n    left: 0;\n    right: 0;\n    z-index: 9999;\n    margin-top: 4px;\n    background: white;\n    border: 1px solid #e0e0e0;\n    border-radius: 4px;\n    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);\n    max-height: 300px;\n    overflow-y: auto;\n    list-style: none !important;\n    padding: 0 !important;\n    margin: 0 !important;\n  }\n  .pro6pp-item {\n    padding: 10px 16px;\n    cursor: pointer;\n    display: flex;\n    flex-direction: row;\n    align-items: center;\n    color: #000000;\n    font-size: 14px;\n    line-height: 1.2;\n    white-space: nowrap;\n    overflow: hidden;\n  }\n  .pro6pp-item:hover, .pro6pp-item--active {\n    background-color: #f5f5f5;\n  }\n  .pro6pp-item__label {\n    font-weight: 500;\n    flex-shrink: 0;\n  }\n  .pro6pp-item__subtitle {\n    font-size: 14px;\n    color: #404040;\n    overflow: hidden;\n    text-overflow: ellipsis;\n    flex-shrink: 1;\n  }\n  .pro6pp-item__chevron {\n    margin-left: auto;\n    display: flex;\n    align-items: center;\n    color: #a3a3a3;\n    padding-left: 8px;\n  }\n  .pro6pp-no-results {\n    padding: 12px;\n    color: #555555;\n    font-size: 14px;\n    text-align: center;\n    user-select: none;\n    pointer-events: none;\n  }\n  .pro6pp-loader {\n    position: absolute;\n    right: 12px;\n    top: 50%;\n    transform: translateY(-50%);\n    width: 16px;\n    height: 16px;\n    border: 2px solid #e0e0e0;\n    border-top-color: #404040;\n    border-radius: 50%;\n    animation: pro6pp-spin 0.6s linear infinite;\n    pointer-events: none;\n  }\n  @keyframes pro6pp-spin {\n    to { transform: translateY(-50%) rotate(360deg); }\n  }\n";
+
+export { type AddressValue, type CountryCode, DEFAULT_STYLES, type Fetcher, INITIAL_STATE, type InferConfig, InferCore, type InferResult, type InferState, type Stage };

package/dist/index.global.js

@@ -1 +1,99 @@
-"use strict";var Pro6PPCore=(()=>{var o=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var S=Object.prototype.hasOwnProperty;var m=(n,t,e)=>t in n?o(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e;var I=(n,t)=>{for(var e in t)o(n,e,{get:t[e],enumerable:!0})},y=(n,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of f(t))!S.call(n,r)&&r!==e&&o(n,r,{get:()=>t[r],enumerable:!(s=p(t,r))||s.enumerable});return n};var v=n=>y(o({},"__esModule",{value:!0}),n);var a=(n,t,e)=>m(n,typeof t!="symbol"?t+"":t,e);var x={};I(x,{INITIAL_STATE:()=>h,InferCore:()=>c});var l={API_URL:"https://api.pro6pp.nl/v2",LIMIT:1e3,DEBOUNCE_MS:300},g={DIGITS_1_3:/^[0-9]{1,3}$/},h={query:"",stage:null,cities:[],streets:[],suggestions:[],isValid:!1,isError:!1,isLoading:!1,selectedSuggestionIndex:-1},c=class{constructor(t){a(this,"country");a(this,"authKey");a(this,"apiUrl");a(this,"limit");a(this,"fetcher");a(this,"onStateChange");a(this,"onSelect");a(this,"state");a(this,"abortController",null);a(this,"debouncedFetch");this.country=t.country,this.authKey=t.authKey,this.apiUrl=t.apiUrl||l.API_URL,this.limit=t.limit||l.LIMIT,this.fetcher=t.fetcher||((e,s)=>fetch(e,s)),this.onStateChange=t.onStateChange||(()=>{}),this.onSelect=t.onSelect||(()=>{}),this.state={...h},this.debouncedFetch=this.debounce(e=>this.executeFetch(e),l.DEBOUNCE_MS)}handleInput(t){this.updateState({query:t,isValid:!1,isLoading:!!t.trim(),selectedSuggestionIndex:-1}),this.state.stage==="final"&&this.onSelect(null),this.debouncedFetch(t)}handleKeyDown(t){let e=t.target;if(!e)return;let s=this.state.cities.length+this.state.streets.length+this.state.suggestions.length;if(s>0){if(t.key==="ArrowDown"){t.preventDefault();let i=this.state.selectedSuggestionIndex+1;i>=s&&(i=0),this.updateState({selectedSuggestionIndex:i});return}if(t.key==="ArrowUp"){t.preventDefault();let i=this.state.selectedSuggestionIndex-1;i<0&&(i=s-1),this.updateState({selectedSuggestionIndex:i});return}if(t.key==="Enter"&&this.state.selectedSuggestionIndex>=0){t.preventDefault();let u=[...this.state.cities,...this.state.streets,...this.state.suggestions][this.state.selectedSuggestionIndex];u&&(this.selectItem(u),this.updateState({selectedSuggestionIndex:-1}));return}}let r=e.value;if(t.key===" "&&this.shouldAutoInsertComma(r)){t.preventDefault();let i=`${r.trim()}, `;this.updateQueryAndFetch(i)}}selectItem(t){let e=typeof t=="string"?t:t.label,s=typeof t!="string"?t.value:void 0,r=typeof t!="string"?t.subtitle:null;if(this.state.stage==="final"){this.finishSelection(e,s);return}this.processSelection(e,r)}shouldAutoInsertComma(t){if(!t.includes(",")&&g.DIGITS_1_3.test(t.trim()))return!0;if(this.state.stage==="house_number"){let s=this.getCurrentFragment(t);return g.DIGITS_1_3.test(s)}return!1}finishSelection(t,e){this.updateState({query:t,suggestions:[],cities:[],streets:[],isValid:!0}),this.onSelect(e||t)}processSelection(t,e){let{stage:s,query:r}=this.state,i=r;if(e&&(s==="city"||s==="street"||s==="mixed")){if(s==="city")i=`${e}, ${t}, `;else{let d=this.getQueryPrefix(r);i=d?`${d} ${t}, ${e}, `:`${t}, ${e}, `}this.updateQueryAndFetch(i);return}if(s==="direct"||s==="addition"){this.finishSelection(t);return}!r.includes(",")&&(s==="city"||s==="street"||s==="house_number_first")?i=`${t}, `:(i=this.replaceLastSegment(r,t),s!=="house_number"&&(i+=", ")),this.updateQueryAndFetch(i)}executeFetch(t){let e=(t||"").toString();if(!e.trim()){this.abortController?.abort(),this.resetState();return}this.updateState({isError:!1}),this.abortController&&this.abortController.abort(),this.abortController=new AbortController;let s=new URL(`${this.apiUrl}/infer/${this.country.toLowerCase()}`),r={authKey:this.authKey,query:e,limit:this.limit.toString()};s.search=new URLSearchParams(r).toString(),this.fetcher(s.toString(),{signal:this.abortController.signal}).then(i=>{if(!i.ok)throw new Error("Network error");return i.json()}).then(i=>this.mapResponseToState(i)).catch(i=>{i.name!=="AbortError"&&this.updateState({isError:!0,isLoading:!1})})}mapResponseToState(t){let e={stage:t.stage,isLoading:!1};t.stage==="mixed"?(e.cities=t.cities||[],e.streets=t.streets||[],e.suggestions=[]):(e.suggestions=t.suggestions||[],e.cities=[],e.streets=[]),e.isValid=t.stage==="final",this.updateState(e)}updateQueryAndFetch(t){this.updateState({query:t,suggestions:[],cities:[],streets:[]}),this.handleInput(t)}replaceLastSegment(t,e){let s=t.lastIndexOf(",");return s===-1?e:`${t.slice(0,s+1)} ${e}`.trim()}getQueryPrefix(t){let e=t.lastIndexOf(",");return e===-1?"":t.slice(0,e+1).trimEnd()}getCurrentFragment(t){return(t.split(",").slice(-1)[0]??"").trim()}resetState(){this.updateState({...h,query:this.state.query})}updateState(t){this.state={...this.state,...t},this.onStateChange(this.state)}debounce(t,e){let s;return(...r)=>{s&&clearTimeout(s),s=setTimeout(()=>t.apply(this,r),e)}}};return v(x);})();
+"use strict";var Pro6PPCore=(()=>{var c=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var I=Object.prototype.hasOwnProperty;var C=(n,e,t)=>e in n?c(n,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):n[e]=t;var T=(n,e)=>{for(var t in e)c(n,t,{get:e[t],enumerable:!0})},w=(n,e,t,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of v(e))!I.call(n,i)&&i!==t&&c(n,i,{get:()=>e[i],enumerable:!(s=y(e,i))||s.enumerable});return n};var _=n=>w(c({},"__esModule",{value:!0}),n);var o=(n,e,t)=>C(n,typeof e!="symbol"?e+"":e,t);var F={};T(F,{DEFAULT_STYLES:()=>b,INITIAL_STATE:()=>h,InferCore:()=>g});var d={API_URL:"https://api.pro6pp.nl/v2",LIMIT:1e3,DEBOUNCE_MS:150,MIN_DEBOUNCE_MS:50},m={DIGITS_1_3:/^[0-9]{1,3}$/},h={query:"",stage:null,cities:[],streets:[],suggestions:[],isValid:!1,isError:!1,isLoading:!1,selectedSuggestionIndex:-1},g=class{constructor(e){o(this,"country");o(this,"authKey");o(this,"apiUrl");o(this,"limit");o(this,"fetcher");o(this,"onStateChange");o(this,"onSelect");o(this,"state");o(this,"abortController",null);o(this,"debouncedFetch");o(this,"isSelecting",!1);this.country=e.country,this.authKey=e.authKey,this.apiUrl=e.apiUrl||d.API_URL,this.limit=e.limit||d.LIMIT,this.fetcher=e.fetcher||((i,r)=>fetch(i,r)),this.onStateChange=e.onStateChange||(()=>{}),this.onSelect=e.onSelect||(()=>{}),this.state={...h};let t=e.debounceMs!==void 0?e.debounceMs:d.DEBOUNCE_MS,s=Math.max(t,d.MIN_DEBOUNCE_MS);this.debouncedFetch=this.debounce(i=>this.executeFetch(i),s)}handleInput(e){if(this.isSelecting){this.isSelecting=!1;return}let t=this.state.stage==="final"&&e!==this.state.query;this.updateState({query:e,isValid:!1,isLoading:!!e.trim(),selectedSuggestionIndex:-1}),t&&this.onSelect(null),this.debouncedFetch(e)}handleKeyDown(e){let t=e.target;if(!t)return;let s=this.state.cities.length+this.state.streets.length+this.state.suggestions.length;if(s>0){if(e.key==="ArrowDown"){e.preventDefault();let r=this.state.selectedSuggestionIndex+1;r>=s&&(r=0),this.updateState({selectedSuggestionIndex:r});return}if(e.key==="ArrowUp"){e.preventDefault();let r=this.state.selectedSuggestionIndex-1;r<0&&(r=s-1),this.updateState({selectedSuggestionIndex:r});return}if(e.key==="Enter"&&this.state.selectedSuggestionIndex>=0){e.preventDefault();let a=[...this.state.cities,...this.state.streets,...this.state.suggestions][this.state.selectedSuggestionIndex];a&&(this.selectItem(a),this.updateState({selectedSuggestionIndex:-1}));return}}let i=t.value;if(e.key===" "&&this.shouldAutoInsertComma(i)){e.preventDefault();let r=`${i.trim()}, `;this.updateQueryAndFetch(r)}}selectItem(e){this.debouncedFetch.cancel(),this.abortController&&this.abortController.abort();let t=typeof e=="string"?e:e.label,s=t;typeof e!="string"&&typeof e.value=="string"&&(s=e.value);let i=typeof e!="string"&&typeof e.value=="object"?e.value:void 0,r=!!i&&Object.keys(i).length>0;if(this.isSelecting=!0,this.state.stage==="final"||r){let p=t;if(i&&Object.keys(i).length>0){let{street:l,street_number:u,house_number:x,city:f}=i,S=u||x;l&&S&&f&&(p=`${l} ${S}, ${f}`)}this.finishSelection(p,i);return}let a=typeof e!="string"?e.subtitle:null;this.processSelection(s,a)}shouldAutoInsertComma(e){if(!e.includes(",")&&m.DIGITS_1_3.test(e.trim()))return!0;if(this.state.stage==="house_number"){let s=this.getCurrentFragment(e);return m.DIGITS_1_3.test(s)}return!1}finishSelection(e,t){this.updateState({query:e,suggestions:[],cities:[],streets:[],isValid:!0,stage:"final"}),this.onSelect(t||e),setTimeout(()=>{this.isSelecting=!1},0)}processSelection(e,t){let{stage:s,query:i}=this.state,r=i;if(t&&(s==="city"||s==="street"||s==="mixed")){if(s==="city")r=`${t}, ${e}, `;else{let u=this.getQueryPrefix(i);r=u?`${u} ${e}, ${t}, `:`${e}, ${t}, `}this.updateQueryAndFetch(r);return}if(s==="direct"||s==="addition"){this.finishSelection(e);return}!i.includes(",")&&(s==="city"||s==="street"||s==="house_number_first")?r=`${e}, `:(r=this.replaceLastSegment(i,e),s!=="house_number"&&(r+=", ")),this.updateQueryAndFetch(r)}executeFetch(e){let t=(e||"").toString();if(!t.trim()){this.abortController?.abort(),this.resetState();return}this.updateState({isError:!1}),this.abortController&&this.abortController.abort(),this.abortController=new AbortController;let s=new URL(`${this.apiUrl}/infer/${this.country.toLowerCase()}`),i={authKey:this.authKey,query:t,limit:this.limit.toString()};s.search=new URLSearchParams(i).toString(),this.fetcher(s.toString(),{signal:this.abortController.signal}).then(r=>{if(!r.ok)throw new Error("Network error");return r.json()}).then(r=>this.mapResponseToState(r)).catch(r=>{r.name!=="AbortError"&&this.updateState({isError:!0,isLoading:!1})})}mapResponseToState(e){let t={stage:e.stage,isLoading:!1},s=!1,i=null,r=e.suggestions||[],a=[],p=new Set;for(let l of r){let u=`${l.label}|${l.subtitle||""}|${JSON.stringify(l.value||{})}`;p.has(u)||(p.add(u),a.push(l))}if(e.stage==="mixed"?(t.cities=e.cities||[],t.streets=e.streets||[],t.suggestions=[]):(t.suggestions=a,t.cities=[],t.streets=[],e.stage==="final"&&a.length===1&&(s=!0,i=a[0])),t.isValid=e.stage==="final",s&&i){t.query=i.label,t.suggestions=[],t.cities=[],t.streets=[],t.isValid=!0,this.updateState(t);let l=typeof i.value=="object"?i.value:i.label;this.onSelect(l)}else this.updateState(t)}updateQueryAndFetch(e){this.updateState({query:e,suggestions:[],cities:[],streets:[]}),this.updateState({isLoading:!0,isValid:!1}),this.debouncedFetch(e),setTimeout(()=>{this.isSelecting=!1},0)}replaceLastSegment(e,t){let s=e.lastIndexOf(",");return s===-1?t:`${e.slice(0,s+1)} ${t}`.trim()}getQueryPrefix(e){let t=e.lastIndexOf(",");return t===-1?"":e.slice(0,t+1).trimEnd()}getCurrentFragment(e){return(e.split(",").slice(-1)[0]??"").trim()}resetState(){this.updateState({...h,query:this.state.query})}updateState(e){this.state={...this.state,...e},this.onStateChange(this.state)}debounce(e,t){let s,i=(...r)=>{s&&clearTimeout(s),s=setTimeout(()=>e.apply(this,r),t)};return i.cancel=()=>{s&&(clearTimeout(s),s=void 0)},i}};var b=`
+  .pro6pp-wrapper {
+    position: relative;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    box-sizing: border-box;
+    width: 100%;
+  }
+  .pro6pp-wrapper * {
+    box-sizing: border-box;
+  }
+  .pro6pp-input {
+    width: 100%;
+    padding: 10px 12px;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    font-size: 16px;
+    line-height: 1.5;
+    transition: border-color 0.2s, box-shadow 0.2s;
+  }
+  .pro6pp-input:focus {
+    outline: none;
+    border-color: #3b82f6;
+    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+  }
+  .pro6pp-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: 9999;
+    margin-top: 4px;
+    background: white;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+    max-height: 300px;
+    overflow-y: auto;
+    list-style: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+  }
+  .pro6pp-item {
+    padding: 10px 16px;
+    cursor: pointer;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    color: #000000;
+    font-size: 14px;
+    line-height: 1.2;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+  .pro6pp-item:hover, .pro6pp-item--active {
+    background-color: #f5f5f5;
+  }
+  .pro6pp-item__label {
+    font-weight: 500;
+    flex-shrink: 0;
+  }
+  .pro6pp-item__subtitle {
+    font-size: 14px;
+    color: #404040;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    flex-shrink: 1;
+  }
+  .pro6pp-item__chevron {
+    margin-left: auto;
+    display: flex;
+    align-items: center;
+    color: #a3a3a3;
+    padding-left: 8px;
+  }
+  .pro6pp-no-results {
+    padding: 12px;
+    color: #555555;
+    font-size: 14px;
+    text-align: center;
+    user-select: none;
+    pointer-events: none;
+  }
+  .pro6pp-loader {
+    position: absolute;
+    right: 12px;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 16px;
+    height: 16px;
+    border: 2px solid #e0e0e0;
+    border-top-color: #404040;
+    border-radius: 50%;
+    animation: pro6pp-spin 0.6s linear infinite;
+    pointer-events: none;
+  }
+  @keyframes pro6pp-spin {
+    to { transform: translateY(-50%) rotate(360deg); }
+  }
+`;return _(F);})();

package/dist/index.js

@@ -1 +1,99 @@
-var g=Object.defineProperty;var p=(a,t,e)=>t in a?g(a,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):a[t]=e;var n=(a,t,e)=>p(a,typeof t!="symbol"?t+"":t,e);var u={API_URL:"https://api.pro6pp.nl/v2",LIMIT:1e3,DEBOUNCE_MS:300},h={DIGITS_1_3:/^[0-9]{1,3}$/},c={query:"",stage:null,cities:[],streets:[],suggestions:[],isValid:!1,isError:!1,isLoading:!1,selectedSuggestionIndex:-1},d=class{constructor(t){n(this,"country");n(this,"authKey");n(this,"apiUrl");n(this,"limit");n(this,"fetcher");n(this,"onStateChange");n(this,"onSelect");n(this,"state");n(this,"abortController",null);n(this,"debouncedFetch");this.country=t.country,this.authKey=t.authKey,this.apiUrl=t.apiUrl||u.API_URL,this.limit=t.limit||u.LIMIT,this.fetcher=t.fetcher||((e,s)=>fetch(e,s)),this.onStateChange=t.onStateChange||(()=>{}),this.onSelect=t.onSelect||(()=>{}),this.state={...c},this.debouncedFetch=this.debounce(e=>this.executeFetch(e),u.DEBOUNCE_MS)}handleInput(t){this.updateState({query:t,isValid:!1,isLoading:!!t.trim(),selectedSuggestionIndex:-1}),this.state.stage==="final"&&this.onSelect(null),this.debouncedFetch(t)}handleKeyDown(t){let e=t.target;if(!e)return;let s=this.state.cities.length+this.state.streets.length+this.state.suggestions.length;if(s>0){if(t.key==="ArrowDown"){t.preventDefault();let i=this.state.selectedSuggestionIndex+1;i>=s&&(i=0),this.updateState({selectedSuggestionIndex:i});return}if(t.key==="ArrowUp"){t.preventDefault();let i=this.state.selectedSuggestionIndex-1;i<0&&(i=s-1),this.updateState({selectedSuggestionIndex:i});return}if(t.key==="Enter"&&this.state.selectedSuggestionIndex>=0){t.preventDefault();let o=[...this.state.cities,...this.state.streets,...this.state.suggestions][this.state.selectedSuggestionIndex];o&&(this.selectItem(o),this.updateState({selectedSuggestionIndex:-1}));return}}let r=e.value;if(t.key===" "&&this.shouldAutoInsertComma(r)){t.preventDefault();let i=`${r.trim()}, `;this.updateQueryAndFetch(i)}}selectItem(t){let e=typeof t=="string"?t:t.label,s=typeof t!="string"?t.value:void 0,r=typeof t!="string"?t.subtitle:null;if(this.state.stage==="final"){this.finishSelection(e,s);return}this.processSelection(e,r)}shouldAutoInsertComma(t){if(!t.includes(",")&&h.DIGITS_1_3.test(t.trim()))return!0;if(this.state.stage==="house_number"){let s=this.getCurrentFragment(t);return h.DIGITS_1_3.test(s)}return!1}finishSelection(t,e){this.updateState({query:t,suggestions:[],cities:[],streets:[],isValid:!0}),this.onSelect(e||t)}processSelection(t,e){let{stage:s,query:r}=this.state,i=r;if(e&&(s==="city"||s==="street"||s==="mixed")){if(s==="city")i=`${e}, ${t}, `;else{let l=this.getQueryPrefix(r);i=l?`${l} ${t}, ${e}, `:`${t}, ${e}, `}this.updateQueryAndFetch(i);return}if(s==="direct"||s==="addition"){this.finishSelection(t);return}!r.includes(",")&&(s==="city"||s==="street"||s==="house_number_first")?i=`${t}, `:(i=this.replaceLastSegment(r,t),s!=="house_number"&&(i+=", ")),this.updateQueryAndFetch(i)}executeFetch(t){let e=(t||"").toString();if(!e.trim()){this.abortController?.abort(),this.resetState();return}this.updateState({isError:!1}),this.abortController&&this.abortController.abort(),this.abortController=new AbortController;let s=new URL(`${this.apiUrl}/infer/${this.country.toLowerCase()}`),r={authKey:this.authKey,query:e,limit:this.limit.toString()};s.search=new URLSearchParams(r).toString(),this.fetcher(s.toString(),{signal:this.abortController.signal}).then(i=>{if(!i.ok)throw new Error("Network error");return i.json()}).then(i=>this.mapResponseToState(i)).catch(i=>{i.name!=="AbortError"&&this.updateState({isError:!0,isLoading:!1})})}mapResponseToState(t){let e={stage:t.stage,isLoading:!1};t.stage==="mixed"?(e.cities=t.cities||[],e.streets=t.streets||[],e.suggestions=[]):(e.suggestions=t.suggestions||[],e.cities=[],e.streets=[]),e.isValid=t.stage==="final",this.updateState(e)}updateQueryAndFetch(t){this.updateState({query:t,suggestions:[],cities:[],streets:[]}),this.handleInput(t)}replaceLastSegment(t,e){let s=t.lastIndexOf(",");return s===-1?e:`${t.slice(0,s+1)} ${e}`.trim()}getQueryPrefix(t){let e=t.lastIndexOf(",");return e===-1?"":t.slice(0,e+1).trimEnd()}getCurrentFragment(t){return(t.split(",").slice(-1)[0]??"").trim()}resetState(){this.updateState({...c,query:this.state.query})}updateState(t){this.state={...this.state,...t},this.onStateChange(this.state)}debounce(t,e){let s;return(...r)=>{s&&clearTimeout(s),s=setTimeout(()=>t.apply(this,r),e)}}};export{c as INITIAL_STATE,d as InferCore};
+var b=Object.defineProperty;var x=(u,e,t)=>e in u?b(u,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):u[e]=t;var n=(u,e,t)=>x(u,typeof e!="symbol"?e+"":e,t);var c={API_URL:"https://api.pro6pp.nl/v2",LIMIT:1e3,DEBOUNCE_MS:150,MIN_DEBOUNCE_MS:50},g={DIGITS_1_3:/^[0-9]{1,3}$/},f={query:"",stage:null,cities:[],streets:[],suggestions:[],isValid:!1,isError:!1,isLoading:!1,selectedSuggestionIndex:-1},S=class{constructor(e){n(this,"country");n(this,"authKey");n(this,"apiUrl");n(this,"limit");n(this,"fetcher");n(this,"onStateChange");n(this,"onSelect");n(this,"state");n(this,"abortController",null);n(this,"debouncedFetch");n(this,"isSelecting",!1);this.country=e.country,this.authKey=e.authKey,this.apiUrl=e.apiUrl||c.API_URL,this.limit=e.limit||c.LIMIT,this.fetcher=e.fetcher||((r,i)=>fetch(r,i)),this.onStateChange=e.onStateChange||(()=>{}),this.onSelect=e.onSelect||(()=>{}),this.state={...f};let t=e.debounceMs!==void 0?e.debounceMs:c.DEBOUNCE_MS,s=Math.max(t,c.MIN_DEBOUNCE_MS);this.debouncedFetch=this.debounce(r=>this.executeFetch(r),s)}handleInput(e){if(this.isSelecting){this.isSelecting=!1;return}let t=this.state.stage==="final"&&e!==this.state.query;this.updateState({query:e,isValid:!1,isLoading:!!e.trim(),selectedSuggestionIndex:-1}),t&&this.onSelect(null),this.debouncedFetch(e)}handleKeyDown(e){let t=e.target;if(!t)return;let s=this.state.cities.length+this.state.streets.length+this.state.suggestions.length;if(s>0){if(e.key==="ArrowDown"){e.preventDefault();let i=this.state.selectedSuggestionIndex+1;i>=s&&(i=0),this.updateState({selectedSuggestionIndex:i});return}if(e.key==="ArrowUp"){e.preventDefault();let i=this.state.selectedSuggestionIndex-1;i<0&&(i=s-1),this.updateState({selectedSuggestionIndex:i});return}if(e.key==="Enter"&&this.state.selectedSuggestionIndex>=0){e.preventDefault();let o=[...this.state.cities,...this.state.streets,...this.state.suggestions][this.state.selectedSuggestionIndex];o&&(this.selectItem(o),this.updateState({selectedSuggestionIndex:-1}));return}}let r=t.value;if(e.key===" "&&this.shouldAutoInsertComma(r)){e.preventDefault();let i=`${r.trim()}, `;this.updateQueryAndFetch(i)}}selectItem(e){this.debouncedFetch.cancel(),this.abortController&&this.abortController.abort();let t=typeof e=="string"?e:e.label,s=t;typeof e!="string"&&typeof e.value=="string"&&(s=e.value);let r=typeof e!="string"&&typeof e.value=="object"?e.value:void 0,i=!!r&&Object.keys(r).length>0;if(this.isSelecting=!0,this.state.stage==="final"||i){let p=t;if(r&&Object.keys(r).length>0){let{street:a,street_number:l,house_number:m,city:d}=r,h=l||m;a&&h&&d&&(p=`${a} ${h}, ${d}`)}this.finishSelection(p,r);return}let o=typeof e!="string"?e.subtitle:null;this.processSelection(s,o)}shouldAutoInsertComma(e){if(!e.includes(",")&&g.DIGITS_1_3.test(e.trim()))return!0;if(this.state.stage==="house_number"){let s=this.getCurrentFragment(e);return g.DIGITS_1_3.test(s)}return!1}finishSelection(e,t){this.updateState({query:e,suggestions:[],cities:[],streets:[],isValid:!0,stage:"final"}),this.onSelect(t||e),setTimeout(()=>{this.isSelecting=!1},0)}processSelection(e,t){let{stage:s,query:r}=this.state,i=r;if(t&&(s==="city"||s==="street"||s==="mixed")){if(s==="city")i=`${t}, ${e}, `;else{let l=this.getQueryPrefix(r);i=l?`${l} ${e}, ${t}, `:`${e}, ${t}, `}this.updateQueryAndFetch(i);return}if(s==="direct"||s==="addition"){this.finishSelection(e);return}!r.includes(",")&&(s==="city"||s==="street"||s==="house_number_first")?i=`${e}, `:(i=this.replaceLastSegment(r,e),s!=="house_number"&&(i+=", ")),this.updateQueryAndFetch(i)}executeFetch(e){let t=(e||"").toString();if(!t.trim()){this.abortController?.abort(),this.resetState();return}this.updateState({isError:!1}),this.abortController&&this.abortController.abort(),this.abortController=new AbortController;let s=new URL(`${this.apiUrl}/infer/${this.country.toLowerCase()}`),r={authKey:this.authKey,query:t,limit:this.limit.toString()};s.search=new URLSearchParams(r).toString(),this.fetcher(s.toString(),{signal:this.abortController.signal}).then(i=>{if(!i.ok)throw new Error("Network error");return i.json()}).then(i=>this.mapResponseToState(i)).catch(i=>{i.name!=="AbortError"&&this.updateState({isError:!0,isLoading:!1})})}mapResponseToState(e){let t={stage:e.stage,isLoading:!1},s=!1,r=null,i=e.suggestions||[],o=[],p=new Set;for(let a of i){let l=`${a.label}|${a.subtitle||""}|${JSON.stringify(a.value||{})}`;p.has(l)||(p.add(l),o.push(a))}if(e.stage==="mixed"?(t.cities=e.cities||[],t.streets=e.streets||[],t.suggestions=[]):(t.suggestions=o,t.cities=[],t.streets=[],e.stage==="final"&&o.length===1&&(s=!0,r=o[0])),t.isValid=e.stage==="final",s&&r){t.query=r.label,t.suggestions=[],t.cities=[],t.streets=[],t.isValid=!0,this.updateState(t);let a=typeof r.value=="object"?r.value:r.label;this.onSelect(a)}else this.updateState(t)}updateQueryAndFetch(e){this.updateState({query:e,suggestions:[],cities:[],streets:[]}),this.updateState({isLoading:!0,isValid:!1}),this.debouncedFetch(e),setTimeout(()=>{this.isSelecting=!1},0)}replaceLastSegment(e,t){let s=e.lastIndexOf(",");return s===-1?t:`${e.slice(0,s+1)} ${t}`.trim()}getQueryPrefix(e){let t=e.lastIndexOf(",");return t===-1?"":e.slice(0,t+1).trimEnd()}getCurrentFragment(e){return(e.split(",").slice(-1)[0]??"").trim()}resetState(){this.updateState({...f,query:this.state.query})}updateState(e){this.state={...this.state,...e},this.onStateChange(this.state)}debounce(e,t){let s,r=(...i)=>{s&&clearTimeout(s),s=setTimeout(()=>e.apply(this,i),t)};return r.cancel=()=>{s&&(clearTimeout(s),s=void 0)},r}};var y=`
+  .pro6pp-wrapper {
+    position: relative;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    box-sizing: border-box;
+    width: 100%;
+  }
+  .pro6pp-wrapper * {
+    box-sizing: border-box;
+  }
+  .pro6pp-input {
+    width: 100%;
+    padding: 10px 12px;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    font-size: 16px;
+    line-height: 1.5;
+    transition: border-color 0.2s, box-shadow 0.2s;
+  }
+  .pro6pp-input:focus {
+    outline: none;
+    border-color: #3b82f6;
+    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+  }
+  .pro6pp-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: 9999;
+    margin-top: 4px;
+    background: white;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+    max-height: 300px;
+    overflow-y: auto;
+    list-style: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+  }
+  .pro6pp-item {
+    padding: 10px 16px;
+    cursor: pointer;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    color: #000000;
+    font-size: 14px;
+    line-height: 1.2;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+  .pro6pp-item:hover, .pro6pp-item--active {
+    background-color: #f5f5f5;
+  }
+  .pro6pp-item__label {
+    font-weight: 500;
+    flex-shrink: 0;
+  }
+  .pro6pp-item__subtitle {
+    font-size: 14px;
+    color: #404040;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    flex-shrink: 1;
+  }
+  .pro6pp-item__chevron {
+    margin-left: auto;
+    display: flex;
+    align-items: center;
+    color: #a3a3a3;
+    padding-left: 8px;
+  }
+  .pro6pp-no-results {
+    padding: 12px;
+    color: #555555;
+    font-size: 14px;
+    text-align: center;
+    user-select: none;
+    pointer-events: none;
+  }
+  .pro6pp-loader {
+    position: absolute;
+    right: 12px;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 16px;
+    height: 16px;
+    border: 2px solid #e0e0e0;
+    border-top-color: #404040;
+    border-radius: 50%;
+    animation: pro6pp-spin 0.6s linear infinite;
+    pointer-events: none;
+  }
+  @keyframes pro6pp-spin {
+    to { transform: translateY(-50%) rotate(360deg); }
+  }
+`;export{y as DEFAULT_STYLES,f as INITIAL_STATE,S as InferCore};

package/package.json

@@ -22,7 +22,7 @@
     "url": "https://github.com/pro6pp/infer-sdk/issues"
   },
   "sideEffects": false,
-  "version": "0.0.2-beta.4",
+  "version": "0.0.2-beta.6",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",