react-country-kit-core 1.1.3 → 1.3.0

package/README.md

@@ -20,26 +20,32 @@ npm install react-country-kit-core
 ## 🛠 Utility Functions
 
 ### Localized Metadata
+
 Get labels and placeholders for billing/registration forms:
 
 ```tsx
-import { 
-  getTaxLabelByCountry, 
-  getTaxPlaceholderByCountry, 
-  getPostalLabelByCountry 
-} from 'react-country-kit-core';
-
-const label = getTaxLabelByCountry('US'); // "EIN / SSN"
-const placeholder = getTaxPlaceholderByCountry('US'); // "00-0000000"
-const postalLabel = getPostalLabelByCountry('JP'); // "Postal Code (〒)"
+import {
+  getTaxLabelByCountry,
+  getTaxPlaceholderByCountry,
+  getPostalLabelByCountry,
+} from "react-country-kit-core";
+
+const label = getTaxLabelByCountry("US"); // "EIN / SSN"
+const placeholder = getTaxPlaceholderByCountry("US"); // "00-0000000"
+const postalLabel = getPostalLabelByCountry("JP"); // "Postal Code (〒)"
 ```
 
 ### Data Retrieval
-```tsx
-import { getAllCountries, getCountryByIso2, searchCountries } from 'react-country-kit-core';
 
-const usa = getCountryByIso2('US');
-const results = searchCountries('united');
+```tsx
+import {
+  getAllCountries,
+  getCountryByIso2,
+  searchCountries,
+} from "react-country-kit-core";
+
+const usa = getCountryByIso2("US");
+const results = searchCountries("united");
 ```
 
 ## 🧠 Headless Hooks
@@ -47,17 +53,23 @@ const results = searchCountries('united');
 Our hooks handle state, filtering, and interaction logic so you can focus on the UI:
 
 ```tsx
-import { useCountryPicker } from 'react-country-kit-core';
+import { useCountryPicker } from "react-country-kit-core";
 
 function CustomPicker() {
-  const { filteredItems, searchQuery, setSearchQuery, selectItem } = useCountryPicker();
-  
+  const { filteredItems, searchQuery, setSearchQuery, selectItem } =
+    useCountryPicker();
+
   return (
     <div>
-      <input value={searchQuery} onChange={(e) => setSearchQuery(e.target.value)} />
+      <input
+        value={searchQuery}
+        onChange={(e) => setSearchQuery(e.target.value)}
+      />
       <ul>
-        {filteredItems.map(c => (
-          <li key={c.iso2} onClick={() => selectItem(c)}>{c.name}</li>
+        {filteredItems.map((c) => (
+          <li key={c.iso2} onClick={() => selectItem(c)}>
+            {c.name}
+          </li>
         ))}
       </ul>
     </div>
@@ -73,6 +85,7 @@ export interface Country {
   iso2: string;
   iso3: string;
   phone_code: string;
+  division_type: string;
   flag: string;
   flag_url: string;
   currency_code: string;

package/dist/data/countries.d.ts

@@ -0,0 +1,10 @@
+import { Country } from '../types';
+/**
+ * Auto-generated country dataset — DO NOT EDIT MANUALLY.
+ * Source: https://raw.githubusercontent.com/kishormainali/country_division_database/refs/heads/main/countries.json
+ * Generated: 2026-05-18T08:54:17.574Z
+ * Countries: 250
+ */
+export declare function iso2ToFlag(iso2: string): string;
+export declare const COUNTRIES: Country[];
+export default COUNTRIES;

package/dist/data/currencies.d.ts

@@ -0,0 +1,3 @@
+import { Currency } from '../types';
+export declare const CURRENCIES: Currency[];
+export default CURRENCIES;

package/dist/data/divisions.d.ts

@@ -0,0 +1,3 @@
+import { Division } from '../types';
+export declare const DIVISIONS: Division[];
+export default DIVISIONS;

package/dist/data/languages.d.ts

@@ -0,0 +1,3 @@
+import { Language } from '../types';
+declare const languages: Language[];
+export default languages;

package/dist/data/phoneFormats.d.ts

@@ -0,0 +1,3 @@
+import { PhoneFormat } from '../types';
+export declare const PHONE_FORMATS: PhoneFormat[];
+export default PHONE_FORMATS;

package/dist/data/timezones.d.ts

@@ -0,0 +1,3 @@
+import { Timezone } from '../types';
+export declare const TIMEZONES: Timezone[];
+export default TIMEZONES;

package/dist/hooks/useBasePicker.d.ts

@@ -0,0 +1,6 @@
+import { UsePickerReturn } from '../types';
+/**
+ * Generic base hook for all pickers.
+ * Handles open/close state, search query, and item selection.
+ */
+export declare function useBasePicker<T>(allItems: T[], filterFn: (items: T[], query: string) => T[], initialValue?: T | null, onChange?: (item: T) => void): UsePickerReturn<T>;

package/dist/hooks/useCountryPicker.d.ts

@@ -0,0 +1,2 @@
+import { Country, UsePickerReturn } from '../types';
+export declare function useCountryPicker(initialValue?: Country | null, onChange?: (country: Country) => void): UsePickerReturn<Country>;

package/dist/hooks/useCurrencyPicker.d.ts

@@ -0,0 +1,2 @@
+import { Currency, UsePickerReturn } from '../types';
+export declare function useCurrencyPicker(initialValue?: Currency | null, onChange?: (currency: Currency) => void): UsePickerReturn<Currency>;

package/dist/hooks/useDivisionPicker.d.ts

@@ -0,0 +1,2 @@
+import { Division, UsePickerReturn } from '../types';
+export declare function useDivisionPicker(countryIso2: string, initialValue?: Division | null, onChange?: (division: Division) => void): UsePickerReturn<Division>;

package/dist/hooks/useLanguagePicker.d.ts

@@ -0,0 +1,2 @@
+import { Language, UsePickerReturn } from '../types';
+export declare function useLanguagePicker(initialValue?: Language | null, onChange?: (language: Language) => void): UsePickerReturn<Language>;

package/dist/hooks/useMultiSelect.d.ts

@@ -0,0 +1,6 @@
+import { UseMultiSelectReturn } from '../types';
+/**
+ * Generic multi-selection hook.
+ * Handles open/close, search, and toggle-selection of multiple items.
+ */
+export declare function useMultiSelect<T>(allItems: T[], filterFn: (items: T[], query: string) => T[], keyFn: (item: T) => string, initialValue?: T[], onChange?: (items: T[]) => void, maxItems?: number): UseMultiSelectReturn<T>;

package/dist/hooks/usePhoneInput.d.ts

@@ -0,0 +1,17 @@
+import { Country, PhoneValue } from '../types';
+export interface UsePhoneInputReturn {
+    country: Country | null;
+    number: string;
+    value: PhoneValue | null;
+    isOpen: boolean;
+    searchQuery: string;
+    filteredCountries: Country[];
+    minLength?: number;
+    maxLength?: number;
+    setSearchQuery: (q: string) => void;
+    selectCountry: (country: Country) => void;
+    setNumber: (num: string) => void;
+    toggle: () => void;
+    close: () => void;
+}
+export declare function usePhoneInput(initialValue?: PhoneValue | null, onChange?: (value: PhoneValue) => void, defaultCountryIso2?: string): UsePhoneInputReturn;

package/dist/hooks/useTimezonePicker.d.ts

@@ -0,0 +1,2 @@
+import { Timezone, UsePickerReturn } from '../types';
+export declare function useTimezonePicker(initialValue?: Timezone | null, onChange?: (timezone: Timezone) => void, countryIso2?: string): UsePickerReturn<Timezone>;

package/dist/index.d.ts

@@ -1,393 +1,19 @@
-export declare const COUNTRIES: Country[];
-
-export declare interface Country {
-    name: string;
-    iso2: string;
-    iso3: string;
-    phone_code: string;
-    phone_format?: PhoneFormat;
-    currency?: Currency;
-    division_type: string;
-    divisions?: Division[];
-    timezones?: Timezone[];
-    /** Emoji flag computed from iso2 */
-    flag: string;
-    /** SVG/Image URL for the country flag */
-    flag_url: string;
-    /** Default language code for the country */
-    language_code: string;
-    /** Default currency code for the country */
-    currency_code: string;
-    /** Label for tax identification number (e.g. "VAT", "SSN", "ABN") */
-    tax_id_label?: string;
-    /** Placeholder for tax identification number */
-    tax_id_placeholder?: string;
-    /** Label for postal/zip code (e.g. "ZIP Code", "Postcode", "PIN Code") */
-    postal_code_label?: string;
-}
-
-export declare interface CountryMultiSelectProps {
-    value: Country[];
-    onChange: (countries: Country[]) => void;
-    placeholder?: string;
-    /** Maximum number of selections (undefined = unlimited) */
-    maxItems?: number;
-    showFlags?: boolean;
-    searchable?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-export declare interface CountryPickerProps {
-    /** Currently selected country */
-    value?: Country | null;
-    /** Callback when user selects a country */
-    onChange: (country: Country) => void;
-    placeholder?: string;
-    /** Enable search input */
-    searchable?: boolean;
-    /** Show emoji flag next to country name */
-    showFlag?: boolean;
-    /** Show phone dial code */
-    showPhoneCode?: boolean;
-    /** Disable the picker */
-    disabled?: boolean;
-    /** Additional wrapper class */
-    className?: string;
-    /** aria-label */
-    label?: string;
-}
-
-export declare const CURRENCIES: Currency[];
-
-export declare interface Currency {
-    code: string;
-    name: string;
-    symbol: string;
-    countryCode: string;
-}
-
-export declare interface CurrencyMultiSelectProps {
-    value: Currency[];
-    onChange: (currencies: Currency[]) => void;
-    placeholder?: string;
-    maxItems?: number;
-    showSymbol?: boolean;
-    searchable?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-export declare interface CurrencyPickerProps {
-    value?: Currency | null;
-    onChange: (currency: Currency) => void;
-    placeholder?: string;
-    searchable?: boolean;
-    /** Filter currencies to a specific country (iso2) and enable auto-selection */
-    countryIso2?: string;
-    /** Auto-select the first currency if countryIso2 is provided. Defaults to true if countryIso2 is present and value is empty. */
-    autoSelect?: boolean;
-    /** Show currency symbol alongside code */
-    showSymbol?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-export declare interface Division {
-    name: string;
-    iso2: string;
-    timezone: string;
-    countryCode: string;
-}
-
-export declare interface DivisionPickerProps {
-    /** ISO2 code of the parent country (required) */
-    countryIso2: string;
-    value?: Division | null;
-    onChange: (division: Division) => void;
-    placeholder?: string;
-    searchable?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-export declare const DIVISIONS: Division[];
-
-/**
- * Returns all countries
- */
-export declare function getAllCountries(): Country[];
-
-/**
- * Returns all unique currencies across all countries
- */
-export declare function getAllCurrencies(): Currency[];
-
-/**
- * Returns all languages
- */
-export declare function getAllLanguages(): Language[];
-
-/**
- * Returns all unique timezones across all countries
- */
-export declare function getAllTimezones(): Timezone[];
-
-/**
- * Find a country by its ISO2 code (case-insensitive)
- */
-export declare function getCountryByIso2(iso2: string): Country | undefined;
-
-/**
- * Find a country by its ISO3 code (case-insensitive)
- */
-export declare function getCountryByIso3(iso3: string): Country | undefined;
-
-/**
- * Find a country by its name (partial, case-insensitive)
- */
-export declare function getCountryByName(name: string): Country | undefined;
-
-/**
- * Find a currency by its code (e.g. "USD")
- */
-export declare function getCurrencyByCode(code: string): Currency | undefined;
-
-/**
- * Get the currency of a country
- */
-/**
- * Get the currency for a country
- */
-export declare function getCurrencyByCountry(iso2: string): Currency | undefined;
-
-/**
- * Get all divisions for a country
- */
-export declare function getDivisionsByCountry(iso2: string): Division[];
-
-/**
- * Find a language by its BCP-47 code
- */
-export declare function getLanguageByCode(code: string): Language | undefined;
-
-/**
- * Get the phone format for a country
- */
-export declare function getPhoneFormatByCountry(iso2: string): PhoneFormat | undefined;
-
-/**
- * Get the min and max phone number lengths for a country
- */
-export declare function getPhoneLengths(iso2: string): {
-    min?: number;
-    max?: number;
-};
-
-/**
- * Get the localized Postal Code label for a country
- */
-export declare function getPostalLabelByCountry(iso2: string): string;
-
-/**
- * Get the localized Tax ID label for a country
- */
-export declare function getTaxLabelByCountry(iso2: string): string;
-
-/**
- * Get the localized Tax ID placeholder for a country
- */
-export declare function getTaxPlaceholderByCountry(iso2: string): string;
-
-/**
- * Find a timezone by its IANA name (e.g. "America/New_York")
- * Supports modern names and common deprecated aliases.
- */
-export declare function getTimezoneByName(name: string): Timezone | undefined;
-
-/**
- * Get all timezones for a country
- */
-export declare function getTimezonesByCountry(iso2: string): Timezone[];
-
-/**
- * Auto-generated country dataset — DO NOT EDIT MANUALLY.
- * Source: https://raw.githubusercontent.com/kishormainali/country_division_database/refs/heads/main/countries.json
- * Generated: 2026-05-15T08:46:14.513Z
- * Countries: 250
- */
-export declare function iso2ToFlag(iso2: string): string;
-
-export declare interface Language {
-    code: string;
-    english_name: string;
-    native_name: string;
-}
-
-export declare interface LanguagePickerProps {
-    value?: Language | null;
-    onChange: (language: Language) => void;
-    placeholder?: string;
-    searchable?: boolean;
-    /** Show native language name alongside english name */
-    showNativeName?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-export declare const PHONE_FORMATS: PhoneFormat[];
-
-export declare interface PhoneFormat {
-    countryCode?: string;
-    iso2: string;
-    dialCode: string;
-    patterns: string;
-    possibleLengths: string;
-    example: string | number;
-}
-
-export declare interface PhoneInputProps {
-    value?: PhoneValue | null;
-    onChange: (value: PhoneValue) => void;
-    /** Pre-select a country by ISO2 on first render */
-    defaultCountryIso2?: string;
-    placeholder?: string;
-    showFlag?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-/**
- * Value object returned by PhoneInput.
- */
-export declare interface PhoneValue {
-    /** Full Country object of the selected country */
-    country: Country;
-    /** Dial code with + prefix, e.g. "+1" */
-    dialCode: string;
-    /** Raw phone number without dial code, e.g. "4155551234" */
-    number: string;
-    /** Full number with dial code, e.g. "+14155551234" */
-    full: string;
-}
-
-/**
- * Search countries by name, iso2, iso3 or phone code
- */
-export declare function searchCountries(query: string): Country[];
-
-/**
- * Search currencies by code, name, or symbol
- */
-export declare function searchCurrencies(query: string, countryIso2?: string): Currency[];
-
-/**
- * Search languages by english name, native name, or code
- */
-export declare function searchLanguages(query: string): Language[];
-
-/**
- * Search timezones by name, abbreviation, or offset string
- */
-export declare function searchTimezones(query: string, countryIso2?: string): Timezone[];
-
-export declare interface Timezone {
-    name: string;
-    offset: number;
-    offset_name: string;
-    abbreviation: string;
-    tzName: string;
-    countryCode: string;
-}
-
-export declare interface TimezonePickerProps {
-    value?: Timezone | null;
-    onChange: (timezone: Timezone) => void;
-    placeholder?: string;
-    searchable?: boolean;
-    /** Filter timezones to a specific country (iso2) and enable auto-selection */
-    countryIso2?: string;
-    /** Auto-select the first timezone if countryIso2 is provided. Defaults to true if countryIso2 is present and value is empty. */
-    autoSelect?: boolean;
-    disabled?: boolean;
-    className?: string;
-    label?: string;
-}
-
-export declare const TIMEZONES: Timezone[];
-
-/**
- * Generic base hook for all pickers.
- * Handles open/close state, search query, and item selection.
- */
-export declare function useBasePicker<T>(allItems: T[], filterFn: (items: T[], query: string) => T[], initialValue?: T | null, onChange?: (item: T) => void): UsePickerReturn<T>;
-
-export declare function useCountryPicker(initialValue?: Country | null, onChange?: (country: Country) => void): UsePickerReturn<Country>;
-
-export declare function useCurrencyPicker(initialValue?: Currency | null, onChange?: (currency: Currency) => void): UsePickerReturn<Currency>;
-
-export declare function useDivisionPicker(countryIso2: string, initialValue?: Division | null, onChange?: (division: Division) => void): UsePickerReturn<Division>;
-
-export declare function useLanguagePicker(initialValue?: Language | null, onChange?: (language: Language) => void): UsePickerReturn<Language>;
-
-/**
- * Generic multi-selection hook.
- * Handles open/close, search, and toggle-selection of multiple items.
- */
-export declare function useMultiSelect<T>(allItems: T[], filterFn: (items: T[], query: string) => T[], keyFn: (item: T) => string, initialValue?: T[], onChange?: (items: T[]) => void, maxItems?: number): UseMultiSelectReturn<T>;
-
-export declare interface UseMultiSelectReturn<T> {
-    isOpen: boolean;
-    searchQuery: string;
-    filteredItems: T[];
-    selectedItems: T[];
-    open: () => void;
-    close: () => void;
-    toggle: () => void;
-    setSearchQuery: (query: string) => void;
-    toggleItem: (item: T) => void;
-    isSelected: (item: T) => boolean;
-    removeItem: (item: T) => void;
-    clearAll: () => void;
-}
-
-export declare function usePhoneInput(initialValue?: PhoneValue | null, onChange?: (value: PhoneValue) => void, defaultCountryIso2?: string): UsePhoneInputReturn;
-
-export declare interface UsePhoneInputReturn {
-    country: Country | null;
-    number: string;
-    value: PhoneValue | null;
-    isOpen: boolean;
-    searchQuery: string;
-    filteredCountries: Country[];
-    minLength?: number;
-    maxLength?: number;
-    setSearchQuery: (q: string) => void;
-    selectCountry: (country: Country) => void;
-    setNumber: (num: string) => void;
-    toggle: () => void;
-    close: () => void;
-}
-
-export declare interface UsePickerReturn<T> {
-    isOpen: boolean;
-    searchQuery: string;
-    filteredItems: T[];
-    selectedItem: T | null;
-    open: () => void;
-    close: () => void;
-    toggle: () => void;
-    setSearchQuery: (query: string) => void;
-    selectItem: (item: T) => void;
-    clearSelection: () => void;
-}
-
-export declare function useTimezonePicker(initialValue?: Timezone | null, onChange?: (timezone: Timezone) => void, countryIso2?: string): UsePickerReturn<Timezone>;
-
-export { }
+export * from './data/countries';
+export * from './data/divisions';
+export * from './data/languages';
+export * from './data/timezones';
+export * from './data/phoneFormats';
+export * from './data/currencies';
+export * from './hooks/useCountryPicker';
+export * from './hooks/useCurrencyPicker';
+export * from './hooks/useDivisionPicker';
+export * from './hooks/useLanguagePicker';
+export * from './hooks/useTimezonePicker';
+export * from './hooks/usePhoneInput';
+export * from './hooks/useMultiSelect';
+export * from './hooks/useBasePicker';
+export * from './utils/countries';
+export * from './utils/currencies';
+export * from './utils/languages';
+export * from './utils/timezones';
+export * from './types';