@pro6pp/infer-react 0.0.2-beta.7 → 0.0.2-beta.8

package/README.md

@@ -42,6 +42,7 @@ You can customize the appearance of the component via the following props:
 | `noResultsText`        | The text to display when no suggestions are found.                                        |
 | `renderItem`           | A custom render function for suggestion items, receiving the `item` and `isActive` state. |
 | `renderNoResults`      | A custom render function for the empty state, receiving the current `state`.              |
+| `debounceMs`           | Delay in ms before API search. Defaults to `150` (min `50`).                              |
 
 ---
 

package/dist/index.cjs

@@ -42,7 +42,8 @@ var import_react = __toESM(require("react"), 1);
 var DEFAULTS = {
   API_URL: "https://api.pro6pp.nl/v2",
   LIMIT: 1e3,
-  DEBOUNCE_MS: 300
+  DEBOUNCE_MS: 150,
+  MIN_DEBOUNCE_MS: 50
 };
 var PATTERNS = {
   DIGITS_1_3: /^[0-9]{1,3}$/
@@ -59,6 +60,10 @@ var INITIAL_STATE = {
   selectedSuggestionIndex: -1
 };
 var InferCore = class {
+  /**
+   * Initializes a new instance of the Infer engine.
+   * @param config The configuration object including API keys and callbacks.
+   */
   constructor(config) {
     __publicField(this, "country");
     __publicField(this, "authKey");
@@ -67,6 +72,10 @@ var InferCore = class {
     __publicField(this, "fetcher");
     __publicField(this, "onStateChange");
     __publicField(this, "onSelect");
+    /**
+     * The current read-only state of the engine.
+     * Use `onStateChange` to react to updates.
+     */
     __publicField(this, "state");
     __publicField(this, "abortController", null);
     __publicField(this, "debouncedFetch");
@@ -81,11 +90,15 @@ var InferCore = class {
     this.onSelect = config.onSelect || (() => {
     });
     this.state = { ...INITIAL_STATE };
-    this.debouncedFetch = this.debounce(
-      (val) => this.executeFetch(val),
-      DEFAULTS.DEBOUNCE_MS
-    );
+    const configDebounce = config.debounceMs !== void 0 ? config.debounceMs : DEFAULTS.DEBOUNCE_MS;
+    const debounceTime = Math.max(configDebounce, DEFAULTS.MIN_DEBOUNCE_MS);
+    this.debouncedFetch = this.debounce((val) => this.executeFetch(val), debounceTime);
   }
+  /**
+   * 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) {
     if (this.isSelecting) {
       this.isSelecting = false;
@@ -103,6 +116,14 @@ var InferCore = class {
     }
     this.debouncedFetch(value);
   }
+  /**
+   * 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) {
     const target = event.target;
     if (!target) return;
@@ -144,6 +165,11 @@ var InferCore = class {
       this.updateQueryAndFetch(next);
     }
   }
+  /**
+   * 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) {
     this.debouncedFetch.cancel();
     if (this.abortController) {
@@ -379,21 +405,18 @@ var DEFAULT_STYLES = `
     list-style: none !important;
     padding: 0 !important;
     margin: 0 !important;
-    overflow: hidden;
   }
   .pro6pp-item {
-    padding: 12px 12px 9px 12px;
+    padding: 10px 16px;
     cursor: pointer;
     display: flex;
     flex-direction: row;
     align-items: center;
     color: #000000;
     font-size: 14px;
-    line-height: 1;
+    line-height: 1.2;
     white-space: nowrap;
     overflow: hidden;
-    border-radius: 0 !important;
-    margin: 0 !important;
   }
   .pro6pp-item:hover, .pro6pp-item--active {
     background-color: #f5f5f5;
@@ -455,15 +478,19 @@ function useInfer(config) {
         }
       }
     });
-  }, [config.country, config.authKey, config.limit]);
+  }, [config.country, config.authKey, config.limit, config.debounceMs]);
   return {
+    /** The current UI state (suggestions, loading status, query, etc.). */
     state,
+    /** The raw InferCore instance for manual control. */
     core,
+    /** Pre-configured event handlers to spread onto an <input /> element. */
     inputProps: {
       value: state.query,
       onChange: (e) => core.handleInput(e.target.value),
       onKeyDown: (e) => core.handleKeyDown(e)
     },
+    /** Function to manually select a specific suggestion. */
     selectItem: (item) => core.selectItem(item)
   };
 }
@@ -479,7 +506,9 @@ var Pro6PPInfer = ({
   ...config
 }) => {
   const { state, selectItem, inputProps: coreInputProps } = useInfer(config);
+  const [isOpen, setIsOpen] = (0, import_react.useState)(false);
   const inputRef = (0, import_react.useRef)(null);
+  const wrapperRef = (0, import_react.useRef)(null);
   (0, import_react.useEffect)(() => {
     if (disableDefaultStyles) return;
     const styleId = "pro6pp-styles";
@@ -490,6 +519,15 @@ var Pro6PPInfer = ({
       document.head.appendChild(styleEl);
     }
   }, [disableDefaultStyles]);
+  (0, import_react.useEffect)(() => {
+    const handleClickOutside = (event) => {
+      if (wrapperRef.current && !wrapperRef.current.contains(event.target)) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
   const items = (0, import_react.useMemo)(() => {
     return [
       ...state.cities.map((c) => ({ ...c, type: "city" })),
@@ -499,14 +537,15 @@ var Pro6PPInfer = ({
   }, [state.cities, state.streets, state.suggestions]);
   const handleSelect = (item) => {
     selectItem(item);
+    setIsOpen(false);
     if (!state.isValid && inputRef.current) {
       inputRef.current.focus();
     }
   };
   const hasResults = items.length > 0;
   const showNoResults = !state.isLoading && !state.isError && state.query.length > 0 && !hasResults && !state.isValid;
-  const showDropdown = hasResults || showNoResults;
-  return /* @__PURE__ */ import_react.default.createElement("div", { className: `pro6pp-wrapper ${className || ""}`, style }, /* @__PURE__ */ import_react.default.createElement("div", { style: { position: "relative" } }, /* @__PURE__ */ import_react.default.createElement(
+  const showDropdown = isOpen && (hasResults || showNoResults);
+  return /* @__PURE__ */ import_react.default.createElement("div", { ref: wrapperRef, className: `pro6pp-wrapper ${className || ""}`, style }, /* @__PURE__ */ import_react.default.createElement("div", { style: { position: "relative" } }, /* @__PURE__ */ import_react.default.createElement(
     "input",
     {
       ref: inputRef,
@@ -515,11 +554,15 @@ var Pro6PPInfer = ({
       placeholder,
       autoComplete: "off",
       ...inputProps,
-      ...coreInputProps
+      ...coreInputProps,
+      onFocus: (e) => {
+        setIsOpen(true);
+        inputProps?.onFocus?.(e);
+      }
     }
   ), state.isLoading && /* @__PURE__ */ import_react.default.createElement("div", { className: "pro6pp-loader" })), showDropdown && /* @__PURE__ */ import_react.default.createElement("ul", { className: "pro6pp-dropdown", role: "listbox" }, hasResults ? items.map((item, index) => {
     const isActive = index === state.selectedSuggestionIndex;
-    const secondaryText = item.subtitle || item.count;
+    const secondaryText = item.subtitle || (item.count !== void 0 ? item.count : "");
     const showChevron = item.value === void 0 || item.value === null;
     return /* @__PURE__ */ import_react.default.createElement(
       "li",

package/dist/index.d.cts

@@ -2,26 +2,56 @@ import React from 'react';
 import { InferConfig, InferState, InferCore, InferResult } from '@pro6pp/infer-core';
 export { AddressValue, CountryCode, Fetcher, InferConfig, InferResult, InferState, Stage } from '@pro6pp/infer-core';
 
+/**
+ * A headless React hook that provides the logic for address search using the Infer API.
+ * @param config The engine configuration (authKey, country, etc.).
+ * @returns An object containing the current state, the core instance, and pre-bound input props.
+ */
 declare function useInfer(config: InferConfig): {
+    /** The current UI state (suggestions, loading status, query, etc.). */
     state: InferState;
+    /** The raw InferCore instance for manual control. */
     core: InferCore;
+    /** Pre-configured event handlers to spread onto an <input /> element. */
     inputProps: {
         value: string;
         onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
         onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
     };
+    /** Function to manually select a specific suggestion. */
     selectItem: (item: InferResult | string) => void;
 };
+/**
+ * Props for the Pro6PPInfer component.
+ */
 interface Pro6PPInferProps extends InferConfig {
+    /** Optional CSS class for the wrapper div. */
     className?: string;
+    /** Optional inline styles for the wrapper div. */
     style?: React.CSSProperties;
+    /** Attributes to pass directly to the underlying input element. */
     inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
+    /** * Custom placeholder text.
+     * @default 'Start typing an address...'
+     */
     placeholder?: string;
+    /** A custom render function for individual suggestion items. */
     renderItem?: (item: InferResult, isActive: boolean) => React.ReactNode;
+    /** * If true, prevents the default CSS theme from being injected.
+     * @default false
+     */
     disableDefaultStyles?: boolean;
+    /** * The text to show when no results are found.
+     * @default 'No results found'
+     */
     noResultsText?: string;
+    /** A custom render function for the "no results" state. */
     renderNoResults?: (state: InferState) => React.ReactNode;
 }
+/**
+ * A styled React component for Pro6PP Infer API.
+ * Includes styling, keyboard navigation, and loading states.
+ */
 declare const Pro6PPInfer: React.FC<Pro6PPInferProps>;
 
 export { Pro6PPInfer, type Pro6PPInferProps, useInfer };

package/dist/index.d.ts

@@ -2,26 +2,56 @@ import React from 'react';
 import { InferConfig, InferState, InferCore, InferResult } from '@pro6pp/infer-core';
 export { AddressValue, CountryCode, Fetcher, InferConfig, InferResult, InferState, Stage } from '@pro6pp/infer-core';
 
+/**
+ * A headless React hook that provides the logic for address search using the Infer API.
+ * @param config The engine configuration (authKey, country, etc.).
+ * @returns An object containing the current state, the core instance, and pre-bound input props.
+ */
 declare function useInfer(config: InferConfig): {
+    /** The current UI state (suggestions, loading status, query, etc.). */
     state: InferState;
+    /** The raw InferCore instance for manual control. */
     core: InferCore;
+    /** Pre-configured event handlers to spread onto an <input /> element. */
     inputProps: {
         value: string;
         onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
         onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
     };
+    /** Function to manually select a specific suggestion. */
     selectItem: (item: InferResult | string) => void;
 };
+/**
+ * Props for the Pro6PPInfer component.
+ */
 interface Pro6PPInferProps extends InferConfig {
+    /** Optional CSS class for the wrapper div. */
     className?: string;
+    /** Optional inline styles for the wrapper div. */
     style?: React.CSSProperties;
+    /** Attributes to pass directly to the underlying input element. */
     inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
+    /** * Custom placeholder text.
+     * @default 'Start typing an address...'
+     */
     placeholder?: string;
+    /** A custom render function for individual suggestion items. */
     renderItem?: (item: InferResult, isActive: boolean) => React.ReactNode;
+    /** * If true, prevents the default CSS theme from being injected.
+     * @default false
+     */
     disableDefaultStyles?: boolean;
+    /** * The text to show when no results are found.
+     * @default 'No results found'
+     */
     noResultsText?: string;
+    /** A custom render function for the "no results" state. */
     renderNoResults?: (state: InferState) => React.ReactNode;
 }
+/**
+ * A styled React component for Pro6PP Infer API.
+ * Includes styling, keyboard navigation, and loading states.
+ */
 declare const Pro6PPInfer: React.FC<Pro6PPInferProps>;
 
 export { Pro6PPInfer, type Pro6PPInferProps, useInfer };

package/dist/index.js

@@ -9,7 +9,8 @@ import React, { useState, useMemo, useEffect, useRef } from "react";
 var DEFAULTS = {
   API_URL: "https://api.pro6pp.nl/v2",
   LIMIT: 1e3,
-  DEBOUNCE_MS: 300
+  DEBOUNCE_MS: 150,
+  MIN_DEBOUNCE_MS: 50
 };
 var PATTERNS = {
   DIGITS_1_3: /^[0-9]{1,3}$/
@@ -26,6 +27,10 @@ var INITIAL_STATE = {
   selectedSuggestionIndex: -1
 };
 var InferCore = class {
+  /**
+   * Initializes a new instance of the Infer engine.
+   * @param config The configuration object including API keys and callbacks.
+   */
   constructor(config) {
     __publicField(this, "country");
     __publicField(this, "authKey");
@@ -34,6 +39,10 @@ var InferCore = class {
     __publicField(this, "fetcher");
     __publicField(this, "onStateChange");
     __publicField(this, "onSelect");
+    /**
+     * The current read-only state of the engine.
+     * Use `onStateChange` to react to updates.
+     */
     __publicField(this, "state");
     __publicField(this, "abortController", null);
     __publicField(this, "debouncedFetch");
@@ -48,11 +57,15 @@ var InferCore = class {
     this.onSelect = config.onSelect || (() => {
     });
     this.state = { ...INITIAL_STATE };
-    this.debouncedFetch = this.debounce(
-      (val) => this.executeFetch(val),
-      DEFAULTS.DEBOUNCE_MS
-    );
+    const configDebounce = config.debounceMs !== void 0 ? config.debounceMs : DEFAULTS.DEBOUNCE_MS;
+    const debounceTime = Math.max(configDebounce, DEFAULTS.MIN_DEBOUNCE_MS);
+    this.debouncedFetch = this.debounce((val) => this.executeFetch(val), debounceTime);
   }
+  /**
+   * 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) {
     if (this.isSelecting) {
       this.isSelecting = false;
@@ -70,6 +83,14 @@ var InferCore = class {
     }
     this.debouncedFetch(value);
   }
+  /**
+   * 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) {
     const target = event.target;
     if (!target) return;
@@ -111,6 +132,11 @@ var InferCore = class {
       this.updateQueryAndFetch(next);
     }
   }
+  /**
+   * 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) {
     this.debouncedFetch.cancel();
     if (this.abortController) {
@@ -346,21 +372,18 @@ var DEFAULT_STYLES = `
     list-style: none !important;
     padding: 0 !important;
     margin: 0 !important;
-    overflow: hidden;
   }
   .pro6pp-item {
-    padding: 12px 12px 9px 12px;
+    padding: 10px 16px;
     cursor: pointer;
     display: flex;
     flex-direction: row;
     align-items: center;
     color: #000000;
     font-size: 14px;
-    line-height: 1;
+    line-height: 1.2;
     white-space: nowrap;
     overflow: hidden;
-    border-radius: 0 !important;
-    margin: 0 !important;
   }
   .pro6pp-item:hover, .pro6pp-item--active {
     background-color: #f5f5f5;
@@ -422,15 +445,19 @@ function useInfer(config) {
         }
       }
     });
-  }, [config.country, config.authKey, config.limit]);
+  }, [config.country, config.authKey, config.limit, config.debounceMs]);
   return {
+    /** The current UI state (suggestions, loading status, query, etc.). */
     state,
+    /** The raw InferCore instance for manual control. */
     core,
+    /** Pre-configured event handlers to spread onto an <input /> element. */
     inputProps: {
       value: state.query,
       onChange: (e) => core.handleInput(e.target.value),
       onKeyDown: (e) => core.handleKeyDown(e)
     },
+    /** Function to manually select a specific suggestion. */
     selectItem: (item) => core.selectItem(item)
   };
 }
@@ -446,7 +473,9 @@ var Pro6PPInfer = ({
   ...config
 }) => {
   const { state, selectItem, inputProps: coreInputProps } = useInfer(config);
+  const [isOpen, setIsOpen] = useState(false);
   const inputRef = useRef(null);
+  const wrapperRef = useRef(null);
   useEffect(() => {
     if (disableDefaultStyles) return;
     const styleId = "pro6pp-styles";
@@ -457,6 +486,15 @@ var Pro6PPInfer = ({
       document.head.appendChild(styleEl);
     }
   }, [disableDefaultStyles]);
+  useEffect(() => {
+    const handleClickOutside = (event) => {
+      if (wrapperRef.current && !wrapperRef.current.contains(event.target)) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
   const items = useMemo(() => {
     return [
       ...state.cities.map((c) => ({ ...c, type: "city" })),
@@ -466,14 +504,15 @@ var Pro6PPInfer = ({
   }, [state.cities, state.streets, state.suggestions]);
   const handleSelect = (item) => {
     selectItem(item);
+    setIsOpen(false);
     if (!state.isValid && inputRef.current) {
       inputRef.current.focus();
     }
   };
   const hasResults = items.length > 0;
   const showNoResults = !state.isLoading && !state.isError && state.query.length > 0 && !hasResults && !state.isValid;
-  const showDropdown = hasResults || showNoResults;
-  return /* @__PURE__ */ React.createElement("div", { className: `pro6pp-wrapper ${className || ""}`, style }, /* @__PURE__ */ React.createElement("div", { style: { position: "relative" } }, /* @__PURE__ */ React.createElement(
+  const showDropdown = isOpen && (hasResults || showNoResults);
+  return /* @__PURE__ */ React.createElement("div", { ref: wrapperRef, className: `pro6pp-wrapper ${className || ""}`, style }, /* @__PURE__ */ React.createElement("div", { style: { position: "relative" } }, /* @__PURE__ */ React.createElement(
     "input",
     {
       ref: inputRef,
@@ -482,11 +521,15 @@ var Pro6PPInfer = ({
       placeholder,
       autoComplete: "off",
       ...inputProps,
-      ...coreInputProps
+      ...coreInputProps,
+      onFocus: (e) => {
+        setIsOpen(true);
+        inputProps?.onFocus?.(e);
+      }
     }
   ), state.isLoading && /* @__PURE__ */ React.createElement("div", { className: "pro6pp-loader" })), showDropdown && /* @__PURE__ */ React.createElement("ul", { className: "pro6pp-dropdown", role: "listbox" }, hasResults ? items.map((item, index) => {
     const isActive = index === state.selectedSuggestionIndex;
-    const secondaryText = item.subtitle || item.count;
+    const secondaryText = item.subtitle || (item.count !== void 0 ? item.count : "");
     const showChevron = item.value === void 0 || item.value === null;
     return /* @__PURE__ */ React.createElement(
       "li",

package/package.json

@@ -20,7 +20,7 @@
     "url": "https://github.com/pro6pp/infer-sdk/issues"
   },
   "sideEffects": false,
-  "version": "0.0.2-beta.7",
+  "version": "0.0.2-beta.8",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -46,7 +46,7 @@
     "react": ">=16"
   },
   "dependencies": {
-    "@pro6pp/infer-core": "0.0.2-beta.5"
+    "@pro6pp/infer-core": "0.0.2-beta.6"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.1",