react-country-kit-core 1.1.0 → 1.1.2

package/README.md

@@ -1,18 +1,67 @@
-# @react-country-kit/core
+# react-country-kit-core
 
-Core datasets, utilities, and hooks for `react-country-kit`.
+The engine behind `react-country-kit`. This package provides all the data, hooks, and utilities needed to build your own custom country-related UI components.
 
 ## 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.
+- **250+ Countries**: Comprehensive dataset with ISO codes (2 & 3), flags, and phone codes.
+- **Administrative Divisions**: State/Province data for major countries.
+- **Currencies & Timezones**: Linked data for every country.
+- **Native Language Support**: English and Native names for languages.
+- **Headless Hooks**: Logic-only hooks (`useCountryPicker`, `usePhoneInput`, etc.) for building custom UI.
+- **Phone Formatting**: Integrated `libphonenumber-js` for accurate phone number handling.
 
 ## Installation
 
 ```bash
-npm install @react-country-kit/core
+npm install react-country-kit-core
+```
+
+## Available Hooks
+
+### `useCountryPicker(initialValue?, onChange?)`
+
+Manages country selection and searching.
+
+### `usePhoneInput(initialValue?, onChange?, defaultCountryIso2?)`
+
+Handles complex phone number input logic, including country switching and validation.
+
+### `useDivisionPicker(countryIso2, initialValue?, onChange?)`
+
+Manages state/province selection for a specific country.
+
+### `useCurrencyPicker(initialValue?, onChange?)`
+
+Manages currency selection.
+
+### `useTimezonePicker(initialValue?, onChange?, countryIso2?)`
+
+Manages timezone selection, optionally filtered by country.
+
+## Utility Functions
+
+- `getAllCountries()`
+- `getCountryByIso2(iso2)`
+- `getDivisionsByCountry(iso2)`
+- `getTimezonesByCountry(iso2)`
+- `searchCountries(query)`
+- ...and many more.
+
+## Data Structure
+
+```typescript
+export interface Country {
+  name: string;
+  iso2: string;
+  iso3: string;
+  phone_code: string;
+  flag: string;
+  flag_url: string;
+  currency_code: string;
+  language_code: string;
+  division_type: string;
+}
 ```
 
 ## License

package/dist/index.d.ts

@@ -18,6 +18,12 @@ export declare interface 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 {
@@ -182,8 +188,24 @@ export declare function getPhoneLengths(iso2: string): {
     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;
 
@@ -195,7 +217,7 @@ 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
+ * Generated: 2026-05-15T08:46:14.513Z
  * Countries: 250
  */
 export declare function iso2ToFlag(iso2: string): string;