react-country-kit-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kishor Mainali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @react-country-kit/core
+
+Core datasets, utilities, and hooks for `react-country-kit`.
+
+## Features
+
+- **Comprehensive Data**: Full datasets for countries, currencies, timezones, languages, and divisions.
+- **Relational Integrity**: Unified `countryCode` links across all datasets.
+- **Phone Formatting**: Powered by `libphonenumber-js` with localized formatting rules.
+- **Performance Optimized**: Optimized React hooks for smooth picker implementations.
+
+## Installation
+
+```bash
+npm install @react-country-kit/core
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+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;
+}
+
+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;
+};
+
+/**
+ * Find a timezone by its IANA name (e.g. "America/New_York")
+ */
+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-15T06:35:47.156Z
+ * 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 { }