react-country-kit-core 1.1.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-country-kit-core",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Core datasets, utilities, and hooks for react-country-kit. Comprehensive data for countries, currencies, timezones, languages, and divisions.",
   "author": "Kishor Mainali",
   "license": "MIT",