react-country-kit-core 1.1.1 → 1.1.3

package/README.md

@@ -1,54 +1,71 @@
 # react-country-kit-core
 
-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.
+The high-performance logic and data engine behind `react-country-kit`. This package provides all the comprehensive datasets, headless hooks, and utilities needed to build custom country-related UI components.
 
-## Features
+## 🚀 Features
 
-- **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.
+- **250+ Countries**: Full dataset with ISO codes, flags, and phone codes.
+- **📑 Localized Metadata**: Built-in support for localized **Tax ID labels** (SSN, VAT, ABN) and **Postal Code labels** (ZIP, PIN, Postcode).
+- **🌍 Global Data**: Timezones (with legacy alias support), Currencies, and Native Language names.
+- **🏙 Administrative Divisions**: State/Province data for all countries.
+- **🧠 Headless Hooks**: Logic-only hooks (`useCountryPicker`, `usePhoneInput`, etc.) for building custom UI with any styling library.
+- **📞 Phone Validation**: Powered by `libphonenumber-js` for accurate formatting and validation.
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install react-country-kit-core
 ```
 
-## Available Hooks
+## 🛠 Utility Functions
 
-### `useCountryPicker(initialValue?, onChange?)`
+### Localized Metadata
+Get labels and placeholders for billing/registration forms:
 
-Manages country selection and searching.
+```tsx
+import { 
+  getTaxLabelByCountry, 
+  getTaxPlaceholderByCountry, 
+  getPostalLabelByCountry 
+} from 'react-country-kit-core';
 
-### `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?)`
+const label = getTaxLabelByCountry('US'); // "EIN / SSN"
+const placeholder = getTaxPlaceholderByCountry('US'); // "00-0000000"
+const postalLabel = getPostalLabelByCountry('JP'); // "Postal Code (〒)"
+```
 
-Manages timezone selection, optionally filtered by country.
+### Data Retrieval
+```tsx
+import { getAllCountries, getCountryByIso2, searchCountries } from 'react-country-kit-core';
 
-## Utility Functions
+const usa = getCountryByIso2('US');
+const results = searchCountries('united');
+```
 
-- `getAllCountries()`
-- `getCountryByIso2(iso2)`
-- `getDivisionsByCountry(iso2)`
-- `getTimezonesByCountry(iso2)`
-- `searchCountries(query)`
-- ...and many more.
+## 🧠 Headless Hooks
+
+Our hooks handle state, filtering, and interaction logic so you can focus on the UI:
+
+```tsx
+import { useCountryPicker } from 'react-country-kit-core';
+
+function CustomPicker() {
+  const { filteredItems, searchQuery, setSearchQuery, selectItem } = useCountryPicker();
+  
+  return (
+    <div>
+      <input value={searchQuery} onChange={(e) => setSearchQuery(e.target.value)} />
+      <ul>
+        {filteredItems.map(c => (
+          <li key={c.iso2} onClick={() => selectItem(c)}>{c.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
 
-## Data Structure
+## 📄 Data Structure
 
 ```typescript
 export interface Country {
@@ -60,10 +77,12 @@ export interface Country {
   flag_url: string;
   currency_code: string;
   language_code: string;
-  division_type: string;
+  tax_id_label: string;
+  tax_id_placeholder: string;
+  postal_code_label: string;
 }
 ```
 
-## License
+## 📄 License
 
 MIT

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;